<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "#">


<html xmlns="#">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Requests 2.9.1 documentation</title>
    
    <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '2.9.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="None" href="index.html#document-index" />
   
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">

  
<!-- RTD Extra Head -->

<!-- 
Always link to the latest version, as canonical.
http://docs.readthedocs.org/en/latest/canonical.html
-->
<link rel="canonical" href="#" />

<link rel="stylesheet" href="#" type="text/css" />

<!-- Add page-specific data, which must exist in the page js, not global -->
<script type="text/javascript">
READTHEDOCS_DATA['page'] = 'index'
</script>

<script type="text/javascript" src="_static/readthedocs-dynamic-include.js"></script>

<!-- end RTD <extrahead> --></head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="nav-item nav-item-0"><a href="index.html#document-index">Requests 2.9.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="requests-http-for-humans">
<h1>Requests: HTTP for Humans<a class="headerlink" href="#requests-http-for-humans" title="Permalink to this headline">¶</a></h1>
<p>Release v2.9.1. (<a class="reference internal" href="index.html#install"><span>Installation</span></a>)</p>
<p>Requests is an <a class="reference internal" href="index.html#apache2"><span>Apache2 Licensed</span></a> HTTP library, written in
Python, for human beings.</p>
<p>Python&#8217;s standard <strong>urllib2</strong> module provides most of
the HTTP capabilities you need, but the API is thoroughly <strong>broken</strong>.
It was built for a different time —&nbsp;and a different web. It requires an
<em>enormous</em> amount of work (even method overrides) to perform the simplest of
tasks.</p>
<p>Things shouldn’t be this way. Not in Python.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/user&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="s1">&#39;pass&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;content-type&#39;</span><span class="p">]</span>
<span class="go">&#39;application/json; charset=utf8&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">encoding</span>
<span class="go">&#39;utf-8&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">u&#39;{&quot;type&quot;:&quot;User&quot;...&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="go">{u&#39;private_gists&#39;: 419, u&#39;total_private_repos&#39;: 77, ...}</span>
</pre></div>
</div>
<p>See <a class="reference external" href="#">similar code, without Requests</a>.</p>
<p>Requests takes all of the work out of Python HTTP/1.1 —&nbsp;making your integration
with web services seamless. There&#8217;s no need to manually add query strings to
your URLs, or to form-encode your POST data. Keep-alive and HTTP connection
pooling are 100%  automatic, powered by <a class="reference external" href="#">urllib3</a>,
which is embedded within Requests.</p>
<div class="section" id="testimonials">
<h2>Testimonials<a class="headerlink" href="#testimonials" title="Permalink to this headline">¶</a></h2>
<p>Her Majesty&#8217;s Government, Amazon, Google, Twilio, Runscope, Mozilla, Heroku,
PayPal, NPR, Obama for America, Transifex, Native Instruments, The Washington
Post, Twitter, SoundCloud, Kippt, Readability, Sony, and Federal US Institutions that prefer to be unnamed
use Requests internally. It has been downloaded over 60,000,000 times from PyPI.</p>
<dl class="docutils">
<dt><strong>Armin Ronacher</strong></dt>
<dd>Requests is the perfect example how beautiful an API can be with the
right level of abstraction.</dd>
<dt><strong>Matt DeBoard</strong></dt>
<dd>I&#8217;m going to get &#64;kennethreitz&#8217;s Python requests module tattooed
on my body, somehow. The whole thing.</dd>
<dt><strong>Daniel Greenfeld</strong></dt>
<dd>Nuked a 1200 LOC spaghetti code library with 10 lines of code thanks to
&#64;kennethreitz&#8217;s request library. Today has been AWESOME.</dd>
<dt><strong>Kenny Meyers</strong></dt>
<dd>Python HTTP: When in doubt, or when not in doubt, use Requests. Beautiful,
simple, Pythonic.</dd>
</dl>
</div>
<div class="section" id="feature-support">
<h2>Feature Support<a class="headerlink" href="#feature-support" title="Permalink to this headline">¶</a></h2>
<p>Requests is ready for today&#8217;s web.</p>
<ul class="simple">
<li>International Domains and URLs</li>
<li>Keep-Alive &amp; Connection Pooling</li>
<li>Sessions with Cookie Persistence</li>
<li>Browser-style SSL Verification</li>
<li>Basic/Digest Authentication</li>
<li>Elegant Key/Value Cookies</li>
<li>Automatic Decompression</li>
<li>Unicode Response Bodies</li>
<li>Multipart File Uploads</li>
<li>Connection Timeouts</li>
<li><code class="docutils literal"><span class="pre">.netrc</span></code> support</li>
<li>Python 2.6—3.4</li>
<li>Thread-safe.</li>
</ul>
</div>
<div class="section" id="user-guide">
<h2>User Guide<a class="headerlink" href="#user-guide" title="Permalink to this headline">¶</a></h2>
<p>This part of the documentation, which is mostly prose, begins with some
background information about Requests, then focuses on step-by-step
instructions for getting the most out of Requests.</p>
<div class="toctree-wrapper compound">
<span id="document-user/intro"></span><div class="section" id="introduction">
<span id="id1"></span><h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h3>
<div class="section" id="philosophy">
<h4>Philosophy<a class="headerlink" href="#philosophy" title="Permalink to this headline">¶</a></h4>
<p>Requests was developed with a few <span class="target" id="index-0"></span><a class="pep reference external" href="#"><strong>PEP 20</strong></a> idioms in mind.</p>
<ol class="arabic simple">
<li>Beautiful is better than ugly.</li>
<li>Explicit is better than implicit.</li>
<li>Simple is better than complex.</li>
<li>Complex is better than complicated.</li>
<li>Readability counts.</li>
</ol>
<p>All contributions to Requests should keep these important rules in mind.</p>
</div>
<div class="section" id="apache2-license">
<span id="apache2"></span><h4>Apache2 License<a class="headerlink" href="#apache2-license" title="Permalink to this headline">¶</a></h4>
<p>A large number of open source projects you find today are <a class="reference external" href="#">GPL Licensed</a>.
While the GPL has its time and place, it should most certainly not be your
go-to license for your next open source project.</p>
<p>A project that is released as GPL cannot be used in any commercial product
without the product itself also being offered as open source.</p>
<p>The MIT, BSD, ISC, and Apache2 licenses are great alternatives to the GPL
that allow your open-source software to be used freely in proprietary,
closed-source software.</p>
<p>Requests is released under terms of <a class="reference external" href="#">Apache2 License</a>.</p>
</div>
<div class="section" id="requests-license">
<h4>Requests License<a class="headerlink" href="#requests-license" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div><p>Copyright 2015 Kenneth Reitz</p>
<blockquote>
<div><p>Licensed under the Apache License, Version 2.0 (the &#8220;License&#8221;);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at</p>
<blockquote>
<div><a class="reference external" href="#">http://www.apache.org/licenses/LICENSE-2.0</a></div></blockquote>
<p>Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an &#8220;AS IS&#8221; BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p>
</div></blockquote>
</div></blockquote>
</div>
</div>
<span id="document-user/install"></span><div class="section" id="installation">
<span id="install"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>
<p>This part of the documentation covers the installation of Requests.
The first step to using any software package is getting it properly installed.</p>
<div class="section" id="distribute-pip">
<h4>Distribute &amp; Pip<a class="headerlink" href="#distribute-pip" title="Permalink to this headline">¶</a></h4>
<p>Installing Requests is simple with <a class="reference external" href="#">pip</a>, just run
this in your terminal:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ pip install requests
</pre></div>
</div>
<p>or, with <a class="reference external" href="#">easy_install</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ easy_install requests
</pre></div>
</div>
<p>But, you really <a class="reference external" href="#">shouldn&#8217;t do that</a>.</p>
</div>
<div class="section" id="get-the-code">
<h4>Get the Code<a class="headerlink" href="#get-the-code" title="Permalink to this headline">¶</a></h4>
<p>Requests is actively developed on GitHub, where the code is
<a class="reference external" href="#">always available</a>.</p>
<p>You can either clone the public repository:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ git clone git://github.com/kennethreitz/requests.git
</pre></div>
</div>
<p>Download the <a class="reference external" href="#">tarball</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ curl -OL https://github.com/kennethreitz/requests/tarball/master
</pre></div>
</div>
<p>Or, download the <a class="reference external" href="#">zipball</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ curl -OL https://github.com/kennethreitz/requests/zipball/master
</pre></div>
</div>
<p>Once you have a copy of the source, you can embed it in your Python package,
or install it into your site-packages easily:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ python setup.py install
</pre></div>
</div>
</div>
</div>
<span id="document-user/quickstart"></span><div class="section" id="quickstart">
<span id="id1"></span><h3>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h3>
<span class="target" id="module-requests.models"></span><p>Eager to get started? This page gives a good introduction in how to get started
with Requests.</p>
<p>First, make sure that:</p>
<ul class="simple">
<li>Requests is <a class="reference internal" href="index.html#install"><span>installed</span></a></li>
<li>Requests is <a class="reference internal" href="index.html#updates"><span>up-to-date</span></a></li>
</ul>
<p>Let&#8217;s get started with some simple examples.</p>
<div class="section" id="make-a-request">
<h4>Make a Request<a class="headerlink" href="#make-a-request" title="Permalink to this headline">¶</a></h4>
<p>Making a request with Requests is very simple.</p>
<p>Begin by importing the Requests module:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
</pre></div>
</div>
<p>Now, let&#8217;s try to get a webpage. For this example, let&#8217;s get GitHub&#8217;s public
timeline</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/events&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Now, we have a <a class="reference internal" href="index.html#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object called <code class="docutils literal"><span class="pre">r</span></code>. We can
get all the information we need from this object.</p>
<p>Requests&#8217; simple API means that all forms of HTTP request are as obvious. For
example, this is how you make an HTTP POST request:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/post&quot;</span><span class="p">,</span> <span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;key&quot;</span><span class="p">:</span><span class="s2">&quot;value&quot;</span><span class="p">})</span>
</pre></div>
</div>
<p>Nice, right? What about the other HTTP request types: PUT, DELETE, HEAD and
OPTIONS? These are all just as simple:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/put&quot;</span><span class="p">,</span> <span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;key&quot;</span><span class="p">:</span><span class="s2">&quot;value&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/delete&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/get&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/get&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>That&#8217;s all well and good, but it&#8217;s also only the start of what Requests can
do.</p>
</div>
<div class="section" id="passing-parameters-in-urls">
<h4>Passing Parameters In URLs<a class="headerlink" href="#passing-parameters-in-urls" title="Permalink to this headline">¶</a></h4>
<p>You often want to send some sort of data in the URL&#8217;s query string. If
you were constructing the URL by hand, this data would be given as key/value
pairs in the URL after a question mark, e.g. <code class="docutils literal"><span class="pre">httpbin.org/get?key=val</span></code>.
Requests allows you to provide these arguments as a dictionary, using the
<code class="docutils literal"><span class="pre">params</span></code> keyword argument. As an example, if you wanted to pass
<code class="docutils literal"><span class="pre">key1=value1</span></code> and <code class="docutils literal"><span class="pre">key2=value2</span></code> to <code class="docutils literal"><span class="pre">httpbin.org/get</span></code>, you would use the
following code:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">payload</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;key1&#39;</span><span class="p">:</span> <span class="s1">&#39;value1&#39;</span><span class="p">,</span> <span class="s1">&#39;key2&#39;</span><span class="p">:</span> <span class="s1">&#39;value2&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/get&quot;</span><span class="p">,</span> <span class="n">params</span><span class="o">=</span><span class="n">payload</span><span class="p">)</span>
</pre></div>
</div>
<p>You can see that the URL has been correctly encoded by printing the URL:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
<span class="go">http://httpbin.org/get?key2=value2&amp;key1=value1</span>
</pre></div>
</div>
<p>Note that any dictionary key whose value is <code class="docutils literal"><span class="pre">None</span></code> will not be added to the
URL&#8217;s query string.</p>
<p>You can also pass a list of items as a value:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">payload</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;key1&#39;</span><span class="p">:</span> <span class="s1">&#39;value1&#39;</span><span class="p">,</span> <span class="s1">&#39;key2&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;value2&#39;</span><span class="p">,</span> <span class="s1">&#39;value3&#39;</span><span class="p">]}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/get&quot;</span><span class="p">,</span> <span class="n">params</span><span class="o">=</span><span class="n">payload</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
<span class="go">http://httpbin.org/get?key1=value1&amp;key2=value2&amp;key2=value3</span>
</pre></div>
</div>
</div>
<div class="section" id="response-content">
<h4>Response Content<a class="headerlink" href="#response-content" title="Permalink to this headline">¶</a></h4>
<p>We can read the content of the server&#8217;s response. Consider the GitHub timeline
again:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/events&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">u&#39;[{&quot;repository&quot;:{&quot;open_issues&quot;:0,&quot;url&quot;:&quot;https://github.com/...</span>
</pre></div>
</div>
<p>Requests will automatically decode content from the server. Most unicode
charsets are seamlessly decoded.</p>
<p>When you make a request, Requests makes educated guesses about the encoding of
the response based on the HTTP headers. The text encoding guessed by Requests
is used when you access <code class="docutils literal"><span class="pre">r.text</span></code>. You can find out what encoding Requests is
using, and change it, using the <code class="docutils literal"><span class="pre">r.encoding</span></code> property:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">encoding</span>
<span class="go">&#39;utf-8&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">encoding</span> <span class="o">=</span> <span class="s1">&#39;ISO-8859-1&#39;</span>
</pre></div>
</div>
<p>If you change the encoding, Requests will use the new value of <code class="docutils literal"><span class="pre">r.encoding</span></code>
whenever you call <code class="docutils literal"><span class="pre">r.text</span></code>. You might want to do this in any situation where
you can apply special logic to work out what the encoding of the content will
be. For example, HTTP and XML have the ability to specify their encoding in
their body. In situations like this, you should use <code class="docutils literal"><span class="pre">r.content</span></code> to find the
encoding, and then set <code class="docutils literal"><span class="pre">r.encoding</span></code>. This will let you use <code class="docutils literal"><span class="pre">r.text</span></code> with
the correct encoding.</p>
<p>Requests will also use custom encodings in the event that you need them. If
you have created your own encoding and registered it with the <code class="docutils literal"><span class="pre">codecs</span></code>
module, you can simply use the codec name as the value of <code class="docutils literal"><span class="pre">r.encoding</span></code> and
Requests will handle the decoding for you.</p>
</div>
<div class="section" id="binary-response-content">
<h4>Binary Response Content<a class="headerlink" href="#binary-response-content" title="Permalink to this headline">¶</a></h4>
<p>You can also access the response body as bytes, for non-text requests:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">content</span>
<span class="go">b&#39;[{&quot;repository&quot;:{&quot;open_issues&quot;:0,&quot;url&quot;:&quot;https://github.com/...</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">gzip</span></code> and <code class="docutils literal"><span class="pre">deflate</span></code> transfer-encodings are automatically decoded for you.</p>
<p>For example, to create an image from binary data returned by a request, you can
use the following code:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">PIL</span> <span class="kn">import</span> <span class="n">Image</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">StringIO</span> <span class="kn">import</span> <span class="n">StringIO</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">i</span> <span class="o">=</span> <span class="n">Image</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">StringIO</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">content</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="json-response-content">
<h4>JSON Response Content<a class="headerlink" href="#json-response-content" title="Permalink to this headline">¶</a></h4>
<p>There&#8217;s also a builtin JSON decoder, in case you&#8217;re dealing with JSON data:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/events&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="go">[{u&#39;repository&#39;: {u&#39;open_issues&#39;: 0, u&#39;url&#39;: &#39;https://github.com/...</span>
</pre></div>
</div>
<p>In case the JSON decoding fails, <code class="docutils literal"><span class="pre">r.json</span></code> raises an exception. For example, if
the response gets a 204 (No Content), or if the response contains invalid JSON,
attempting <code class="docutils literal"><span class="pre">r.json</span></code> raises <code class="docutils literal"><span class="pre">ValueError:</span> <span class="pre">No</span> <span class="pre">JSON</span> <span class="pre">object</span> <span class="pre">could</span> <span class="pre">be</span> <span class="pre">decoded</span></code>.</p>
<p>It should be noted that the success of the call to <code class="docutils literal"><span class="pre">r.json</span></code> does <strong>not</strong>
indicate the success of the response. Some servers may return a JSON object in a
failed response (e.g. error details with HTTP 500). Such JSON will be decoded
and returned. To check that a request is successful, use
<code class="docutils literal"><span class="pre">r.raise_for_status()</span></code> or check <code class="docutils literal"><span class="pre">r.status_code</span></code> is what you expect.</p>
</div>
<div class="section" id="raw-response-content">
<h4>Raw Response Content<a class="headerlink" href="#raw-response-content" title="Permalink to this headline">¶</a></h4>
<p>In the rare case that you&#8217;d like to get the raw socket response from the
server, you can access <code class="docutils literal"><span class="pre">r.raw</span></code>. If you want to do this, make sure you set
<code class="docutils literal"><span class="pre">stream=True</span></code> in your initial request. Once you do, you can do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/events&#39;</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">raw</span>
<span class="go">&lt;requests.packages.urllib3.response.HTTPResponse object at 0x101194810&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">raw</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="go">&#39;\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03&#39;</span>
</pre></div>
</div>
<p>In general, however, you should use a pattern like this to save what is being
streamed to a file:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s1">&#39;wb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">fd</span><span class="p">:</span>
    <span class="k">for</span> <span class="n">chunk</span> <span class="ow">in</span> <span class="n">r</span><span class="o">.</span><span class="n">iter_content</span><span class="p">(</span><span class="n">chunk_size</span><span class="p">):</span>
        <span class="n">fd</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">chunk</span><span class="p">)</span>
</pre></div>
</div>
<p>Using <code class="docutils literal"><span class="pre">Response.iter_content</span></code> will handle a lot of what you would otherwise
have to handle when using <code class="docutils literal"><span class="pre">Response.raw</span></code> directly. When streaming a
download, the above is the preferred and recommended way to retrieve the
content.</p>
</div>
<div class="section" id="custom-headers">
<h4>Custom Headers<a class="headerlink" href="#custom-headers" title="Permalink to this headline">¶</a></h4>
<p>If you&#8217;d like to add HTTP headers to a request, simply pass in a <code class="docutils literal"><span class="pre">dict</span></code> to the
<code class="docutils literal"><span class="pre">headers</span></code> parameter.</p>
<p>For example, we didn&#8217;t specify our user-agent in the previous example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">json</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;https://api.github.com/some/endpoint&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">headers</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;user-agent&#39;</span><span class="p">:</span> <span class="s1">&#39;my-app/0.0.1&#39;</span><span class="p">}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="n">headers</span><span class="p">)</span>
</pre></div>
</div>
<p>Note: Custom headers are given less precedence than more specific sources of information. For instance:</p>
<ul class="simple">
<li>Authorization headers will be overridden if credentials are passed via the <code class="docutils literal"><span class="pre">auth</span></code> parameter or are specified in a <code class="docutils literal"><span class="pre">.netrc</span></code> accessible in the environment.</li>
<li>Authorization headers will be removed if you get redirected off-host.</li>
<li>Proxy-Authorization headers will be overridden by proxy credentials provided in the URL.</li>
<li>Content-Length headers will be overridden when we can determine the length of the content.</li>
</ul>
<p>Furthermore, Requests does not change its behavior at all based on which custom headers are specified. The headers are simply passed on into the final request.</p>
</div>
<div class="section" id="more-complicated-post-requests">
<h4>More complicated POST requests<a class="headerlink" href="#more-complicated-post-requests" title="Permalink to this headline">¶</a></h4>
<p>Typically, you want to send some form-encoded data — much like an HTML form.
To do this, simply pass a dictionary to the <code class="docutils literal"><span class="pre">data</span></code> argument. Your
dictionary of data will automatically be form-encoded when the request is made:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">payload</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;key1&#39;</span><span class="p">:</span> <span class="s1">&#39;value1&#39;</span><span class="p">,</span> <span class="s1">&#39;key2&#39;</span><span class="p">:</span> <span class="s1">&#39;value2&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/post&quot;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">payload</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &quot;form&quot;: {</span>
<span class="go">    &quot;key2&quot;: &quot;value2&quot;,</span>
<span class="go">    &quot;key1&quot;: &quot;value1&quot;</span>
<span class="go">  },</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
<p>There are many times that you want to send data that is not form-encoded. If
you pass in a <code class="docutils literal"><span class="pre">string</span></code> instead of a <code class="docutils literal"><span class="pre">dict</span></code>, that data will be posted directly.</p>
<p>For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">json</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;https://api.github.com/some/endpoint&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">payload</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;some&#39;</span><span class="p">:</span> <span class="s1">&#39;data&#39;</span><span class="p">}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="n">payload</span><span class="p">))</span>
</pre></div>
</div>
<p>Instead of encoding the <code class="docutils literal"><span class="pre">dict</span></code> yourself, you can also pass it directly using
the <code class="docutils literal"><span class="pre">json</span></code> parameter (added in version 2.4.2) and it will be encoded automatically:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;https://api.github.com/some/endpoint&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">payload</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;some&#39;</span><span class="p">:</span> <span class="s1">&#39;data&#39;</span><span class="p">}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">json</span><span class="o">=</span><span class="n">payload</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="post-a-multipart-encoded-file">
<h4>POST a Multipart-Encoded File<a class="headerlink" href="#post-a-multipart-encoded-file" title="Permalink to this headline">¶</a></h4>
<p>Requests makes it simple to upload Multipart-encoded files:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/post&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">files</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;file&#39;</span><span class="p">:</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;report.xls&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="n">files</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &quot;files&quot;: {</span>
<span class="go">    &quot;file&quot;: &quot;&lt;censored...binary...data&gt;&quot;</span>
<span class="go">  },</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
<p>You can set the filename, content_type and headers explicitly:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/post&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">files</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;file&#39;</span><span class="p">:</span> <span class="p">(</span><span class="s1">&#39;report.xls&#39;</span><span class="p">,</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;report.xls&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">),</span> <span class="s1">&#39;application/vnd.ms-excel&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s1">&#39;Expires&#39;</span><span class="p">:</span> <span class="s1">&#39;0&#39;</span><span class="p">})}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="n">files</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &quot;files&quot;: {</span>
<span class="go">    &quot;file&quot;: &quot;&lt;censored...binary...data&gt;&quot;</span>
<span class="go">  },</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
<p>If you want, you can send strings to be received as files:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/post&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">files</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;file&#39;</span><span class="p">:</span> <span class="p">(</span><span class="s1">&#39;report.csv&#39;</span><span class="p">,</span> <span class="s1">&#39;some,data,to,send</span><span class="se">\n</span><span class="s1">another,row,to,send</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="n">files</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &quot;files&quot;: {</span>
<span class="go">    &quot;file&quot;: &quot;some,data,to,send\\nanother,row,to,send\\n&quot;</span>
<span class="go">  },</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
<p>In the event you are posting a very large file as a <code class="docutils literal"><span class="pre">multipart/form-data</span></code>
request, you may want to stream the request. By default, <code class="docutils literal"><span class="pre">requests</span></code> does not
support this, but there is a separate package which does -
<code class="docutils literal"><span class="pre">requests-toolbelt</span></code>. You should read <a class="reference external" href="#">the toolbelt&#8217;s documentation</a> for more details about how to use it.</p>
<p>For sending multiple files in one request refer to the <a class="reference internal" href="index.html#advanced"><span>advanced</span></a>
section.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is strongly recommended that you open files in <a class="reference external" href="#">binary mode</a>.
This is because Requests may attempt to provide the
<code class="docutils literal"><span class="pre">Content-Length</span></code> header for you, and if it does this value will
be set to the number of <em>bytes</em> in the file. Errors may occur if
you open the file in <em>text mode</em>.</p>
</div>
</div>
<div class="section" id="response-status-codes">
<h4>Response Status Codes<a class="headerlink" href="#response-status-codes" title="Permalink to this headline">¶</a></h4>
<p>We can check the response status code:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
</pre></div>
</div>
<p>Requests also comes with a built-in status code lookup object for easy
reference:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="o">.</span><span class="n">ok</span>
<span class="go">True</span>
</pre></div>
</div>
<p>If we made a bad request (a 4XX client error or 5XX server error response), we
can raise it with
<a class="reference internal" href="index.html#requests.Response.raise_for_status" title="requests.Response.raise_for_status"><code class="xref py py-meth docutils literal"><span class="pre">Response.raise_for_status()</span></code></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">bad_r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/status/404&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bad_r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">404</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">bad_r</span><span class="o">.</span><span class="n">raise_for_status</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;requests/models.py&quot;</span>, line <span class="m">832</span>, in <span class="n">raise_for_status</span>
    <span class="k">raise</span> <span class="n">http_error</span>
<span class="gr">requests.exceptions.HTTPError</span>: <span class="n">404 Client Error</span>
</pre></div>
</div>
<p>But, since our <code class="docutils literal"><span class="pre">status_code</span></code> for <code class="docutils literal"><span class="pre">r</span></code> was <code class="docutils literal"><span class="pre">200</span></code>, when we call
<code class="docutils literal"><span class="pre">raise_for_status()</span></code> we get:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">raise_for_status</span><span class="p">()</span>
<span class="go">None</span>
</pre></div>
</div>
<p>All is well.</p>
</div>
<div class="section" id="response-headers">
<h4>Response Headers<a class="headerlink" href="#response-headers" title="Permalink to this headline">¶</a></h4>
<p>We can view the server&#8217;s response headers using a Python dictionary:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span>
<span class="go">{</span>
<span class="go">    &#39;content-encoding&#39;: &#39;gzip&#39;,</span>
<span class="go">    &#39;transfer-encoding&#39;: &#39;chunked&#39;,</span>
<span class="go">    &#39;connection&#39;: &#39;close&#39;,</span>
<span class="go">    &#39;server&#39;: &#39;nginx/1.0.4&#39;,</span>
<span class="go">    &#39;x-runtime&#39;: &#39;148ms&#39;,</span>
<span class="go">    &#39;etag&#39;: &#39;&quot;e1ca502697e5c9317743dc078f67693f&quot;&#39;,</span>
<span class="go">    &#39;content-type&#39;: &#39;application/json&#39;</span>
<span class="go">}</span>
</pre></div>
</div>
<p>The dictionary is special, though: it&#8217;s made just for HTTP headers. According to
<a class="reference external" href="#">RFC 7230</a>, HTTP Header names
are case-insensitive.</p>
<p>So, we can access the headers using any capitalization we want:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;Content-Type&#39;</span><span class="p">]</span>
<span class="go">&#39;application/json&#39;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;content-type&#39;</span><span class="p">)</span>
<span class="go">&#39;application/json&#39;</span>
</pre></div>
</div>
<p>It is also special in that the server could have sent the same header multiple
times with different values, but requests combines them so they can be
represented in the dictionary within a single mapping, as per
<a class="reference external" href="#">RFC 7230</a>:</p>
<blockquote>
<div>A recipient MAY combine multiple header fields with the same field name
into one &#8220;field-name: field-value&#8221; pair, without changing the semantics
of the message, by appending each subsequent field value to the combined
field value in order, separated by a comma.</div></blockquote>
</div>
<div class="section" id="cookies">
<h4>Cookies<a class="headerlink" href="#cookies" title="Permalink to this headline">¶</a></h4>
<p>If a response contains some Cookies, you can quickly access them:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://example.com/some/cookie/setting/url&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">cookies</span><span class="p">[</span><span class="s1">&#39;example_cookie_name&#39;</span><span class="p">]</span>
<span class="go">&#39;example_cookie_value&#39;</span>
</pre></div>
</div>
<p>To send your own cookies to the server, you can use the <code class="docutils literal"><span class="pre">cookies</span></code>
parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/cookies&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cookies</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">cookies_are</span><span class="o">=</span><span class="s1">&#39;working&#39;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">cookies</span><span class="o">=</span><span class="n">cookies</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">&#39;{&quot;cookies&quot;: {&quot;cookies_are&quot;: &quot;working&quot;}}&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="redirection-and-history">
<h4>Redirection and History<a class="headerlink" href="#redirection-and-history" title="Permalink to this headline">¶</a></h4>
<p>By default Requests will perform location redirection for all verbs except
HEAD.</p>
<p>We can use the <code class="docutils literal"><span class="pre">history</span></code> property of the Response object to track redirection.</p>
<p>The <a class="reference internal" href="index.html#requests.Response.history" title="requests.Response.history"><code class="xref py py-meth docutils literal"><span class="pre">Response.history</span></code></a> list contains the
<a class="reference internal" href="index.html#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> objects that were created in order to
complete the request. The list is sorted from the oldest to the most recent
response.</p>
<p>For example, GitHub redirects all HTTP requests to HTTPS:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://github.com&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">url</span>
<span class="go">&#39;https://github.com/&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">history</span>
<span class="go">[&lt;Response [301]&gt;]</span>
</pre></div>
</div>
<p>If you&#8217;re using GET, OPTIONS, POST, PUT, PATCH or DELETE, you can disable
redirection handling with the <code class="docutils literal"><span class="pre">allow_redirects</span></code> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://github.com&#39;</span><span class="p">,</span> <span class="n">allow_redirects</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">301</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">history</span>
<span class="go">[]</span>
</pre></div>
</div>
<p>If you&#8217;re using HEAD, you can enable redirection as well:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="s1">&#39;http://github.com&#39;</span><span class="p">,</span> <span class="n">allow_redirects</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">url</span>
<span class="go">&#39;https://github.com/&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">history</span>
<span class="go">[&lt;Response [301]&gt;]</span>
</pre></div>
</div>
</div>
<div class="section" id="timeouts">
<h4>Timeouts<a class="headerlink" href="#timeouts" title="Permalink to this headline">¶</a></h4>
<p>You can tell Requests to stop waiting for a response after a given number of
seconds with the <code class="docutils literal"><span class="pre">timeout</span></code> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mf">0.001</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
  File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>
<span class="gr">requests.exceptions.Timeout</span>: <span class="n">HTTPConnectionPool(host=&#39;github.com&#39;, port=80): Request timed out. (timeout=0.001)</span>
</pre></div>
</div>
<div class="admonition-note admonition">
<p class="first admonition-title">Note</p>
<p class="last"><code class="docutils literal"><span class="pre">timeout</span></code> is not a time limit on the entire response download;
rather, an exception is raised if the server has not issued a
response for <code class="docutils literal"><span class="pre">timeout</span></code> seconds (more precisely, if no bytes have been
received on the underlying socket for <code class="docutils literal"><span class="pre">timeout</span></code> seconds).</p>
</div>
</div>
<div class="section" id="errors-and-exceptions">
<h4>Errors and Exceptions<a class="headerlink" href="#errors-and-exceptions" title="Permalink to this headline">¶</a></h4>
<p>In the event of a network problem (e.g. DNS failure, refused connection, etc),
Requests will raise a <a class="reference internal" href="index.html#requests.exceptions.ConnectionError" title="requests.exceptions.ConnectionError"><code class="xref py py-class docutils literal"><span class="pre">ConnectionError</span></code></a> exception.</p>
<p>In the rare event of an invalid HTTP response, Requests will raise an
<a class="reference internal" href="index.html#requests.exceptions.HTTPError" title="requests.exceptions.HTTPError"><code class="xref py py-class docutils literal"><span class="pre">HTTPError</span></code></a> exception.</p>
<p>If a request times out, a <a class="reference internal" href="index.html#requests.exceptions.Timeout" title="requests.exceptions.Timeout"><code class="xref py py-class docutils literal"><span class="pre">Timeout</span></code></a> exception is
raised.</p>
<p>If a request exceeds the configured number of maximum redirections, a
<a class="reference internal" href="index.html#requests.exceptions.TooManyRedirects" title="requests.exceptions.TooManyRedirects"><code class="xref py py-class docutils literal"><span class="pre">TooManyRedirects</span></code></a> exception is raised.</p>
<p>All exceptions that Requests explicitly raises inherit from
<a class="reference internal" href="index.html#requests.exceptions.RequestException" title="requests.exceptions.RequestException"><code class="xref py py-class docutils literal"><span class="pre">requests.exceptions.RequestException</span></code></a>.</p>
<hr class="docutils" />
<p>Ready for more? Check out the <a class="reference internal" href="index.html#advanced"><span>advanced</span></a> section.</p>
</div>
</div>
<span id="document-user/advanced"></span><div class="section" id="advanced-usage">
<span id="advanced"></span><h3>Advanced Usage<a class="headerlink" href="#advanced-usage" title="Permalink to this headline">¶</a></h3>
<p>This document covers some of Requests more advanced features.</p>
<div class="section" id="session-objects">
<span id="id1"></span><h4>Session Objects<a class="headerlink" href="#session-objects" title="Permalink to this headline">¶</a></h4>
<p>The Session object allows you to persist certain parameters across
requests. It also persists cookies across all requests made from the
Session instance, and will use <code class="docutils literal"><span class="pre">urllib3</span></code>&#8216;s <a class="reference external" href="#">connection pooling</a>. So if
you&#8217;re making several requests to the same host, the underlying TCP
connection will be reused, which can result in a significant performance
increase (see <a class="reference external" href="#">HTTP persistent connection</a>).</p>
<p>A Session object has all the methods of the main Requests API.</p>
<p>Let&#8217;s persist some cookies across requests:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>

<span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/cookies/set/sessioncookie/123456789&#39;</span><span class="p">)</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;http://httpbin.org/cookies&quot;</span><span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="c1"># &#39;{&quot;cookies&quot;: {&quot;sessioncookie&quot;: &quot;123456789&quot;}}&#39;</span>
</pre></div>
</div>
<p>Sessions can also be used to provide default data to the request methods. This
is done by providing data to the properties on a Session object:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="n">s</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="s1">&#39;pass&#39;</span><span class="p">)</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">&#39;x-test&#39;</span><span class="p">:</span> <span class="s1">&#39;true&#39;</span><span class="p">})</span>

<span class="c1"># both &#39;x-test&#39; and &#39;x-test2&#39; are sent</span>
<span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/headers&#39;</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;x-test2&#39;</span><span class="p">:</span> <span class="s1">&#39;true&#39;</span><span class="p">})</span>
</pre></div>
</div>
<p>Any dictionaries that you pass to a request method will be merged with the
session-level values that are set. The method-level parameters override session
parameters.</p>
<p>Note, however, that method-level parameters will <em>not</em> be persisted across
requests, even if using a session. This example will only send the cookies
with the first request, but not the second:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/cookies&#39;</span><span class="p">,</span> <span class="n">cookies</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;from-my&#39;</span><span class="p">:</span> <span class="s1">&#39;browser&#39;</span><span class="p">})</span>
<span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="c1"># &#39;{&quot;cookies&quot;: {&quot;from-my&quot;: &quot;browser&quot;}}&#39;</span>

<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/cookies&#39;</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="c1"># &#39;{&quot;cookies&quot;: {}}&#39;</span>
</pre></div>
</div>
<p>If you want to manually add cookies to your session, use the
<a class="reference internal" href="index.html#api-cookies"><span>Cookie utility functions</span></a> to manipulate
<a class="reference internal" href="index.html#requests.Session.cookies" title="requests.Session.cookies"><code class="xref py py-attr docutils literal"><span class="pre">Session.cookies</span></code></a>.</p>
<p>Sessions can also be used as context managers:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span> <span class="k">as</span> <span class="n">s</span><span class="p">:</span>
    <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/cookies/set/sessioncookie/123456789&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>This will make sure the session is closed as soon as the <code class="docutils literal"><span class="pre">with</span></code> block is
exited, even if unhandled exceptions occurred.</p>
<div class="admonition-remove-a-value-from-a-dict-parameter admonition">
<p class="first admonition-title">Remove a Value From a Dict Parameter</p>
<p class="last">Sometimes you&#8217;ll want to omit session-level keys from a dict parameter. To
do this, you simply set that key&#8217;s value to <code class="docutils literal"><span class="pre">None</span></code> in the method-level
parameter. It will automatically be omitted.</p>
</div>
<p>All values that are contained within a session are directly available to you.
See the <a class="reference internal" href="index.html#sessionapi"><span>Session API Docs</span></a> to learn more.</p>
</div>
<div class="section" id="request-and-response-objects">
<span id="id2"></span><h4>Request and Response Objects<a class="headerlink" href="#request-and-response-objects" title="Permalink to this headline">¶</a></h4>
<p>Whenever a call is made to <code class="docutils literal"><span class="pre">requests.get()</span></code> and friends you are doing two
major things. First, you are constructing a <code class="docutils literal"><span class="pre">Request</span></code> object which will be
sent off to a server to request or query some resource. Second, a <code class="docutils literal"><span class="pre">Response</span></code>
object is generated once <code class="docutils literal"><span class="pre">requests</span></code> gets a response back from the server.
The Response object contains all of the information returned by the server and
also contains the <code class="docutils literal"><span class="pre">Request</span></code> object you created originally. Here is a simple
request to get some very important information from Wikipedia&#8217;s servers:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://en.wikipedia.org/wiki/Monty_Python&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>If we want to access the headers the server sent back to us, we do this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span>
<span class="go">{&#39;content-length&#39;: &#39;56170&#39;, &#39;x-content-type-options&#39;: &#39;nosniff&#39;, &#39;x-cache&#39;:</span>
<span class="go">&#39;HIT from cp1006.eqiad.wmnet, MISS from cp1010.eqiad.wmnet&#39;, &#39;content-encoding&#39;:</span>
<span class="go">&#39;gzip&#39;, &#39;age&#39;: &#39;3080&#39;, &#39;content-language&#39;: &#39;en&#39;, &#39;vary&#39;: &#39;Accept-Encoding,Cookie&#39;,</span>
<span class="go">&#39;server&#39;: &#39;Apache&#39;, &#39;last-modified&#39;: &#39;Wed, 13 Jun 2012 01:33:50 GMT&#39;,</span>
<span class="go">&#39;connection&#39;: &#39;close&#39;, &#39;cache-control&#39;: &#39;private, s-maxage=0, max-age=0,</span>
<span class="go">must-revalidate&#39;, &#39;date&#39;: &#39;Thu, 14 Jun 2012 12:59:39 GMT&#39;, &#39;content-type&#39;:</span>
<span class="go">&#39;text/html; charset=UTF-8&#39;, &#39;x-cache-lookup&#39;: &#39;HIT from cp1006.eqiad.wmnet:3128,</span>
<span class="go">MISS from cp1010.eqiad.wmnet:80&#39;}</span>
</pre></div>
</div>
<p>However, if we want to get the headers we sent the server, we simply access the
request, and then the request&#8217;s headers:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">headers</span>
<span class="go">{&#39;Accept-Encoding&#39;: &#39;identity, deflate, compress, gzip&#39;,</span>
<span class="go">&#39;Accept&#39;: &#39;*/*&#39;, &#39;User-Agent&#39;: &#39;python-requests/1.2.0&#39;}</span>
</pre></div>
</div>
</div>
<div class="section" id="prepared-requests">
<span id="id3"></span><h4>Prepared Requests<a class="headerlink" href="#prepared-requests" title="Permalink to this headline">¶</a></h4>
<p>Whenever you receive a <a class="reference internal" href="index.html#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object
from an API call or a Session call, the <code class="docutils literal"><span class="pre">request</span></code> attribute is actually the
<code class="docutils literal"><span class="pre">PreparedRequest</span></code> that was used. In some cases you may wish to do some extra
work to the body or headers (or anything else really) before sending a
request. The simple recipe for this is the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">requests</span> <span class="kn">import</span> <span class="n">Request</span><span class="p">,</span> <span class="n">Session</span>

<span class="n">s</span> <span class="o">=</span> <span class="n">Session</span><span class="p">()</span>
<span class="n">req</span> <span class="o">=</span> <span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="n">url</span><span class="p">,</span>
    <span class="n">data</span><span class="o">=</span><span class="n">data</span><span class="p">,</span>
    <span class="n">headers</span><span class="o">=</span><span class="n">header</span>
<span class="p">)</span>
<span class="n">prepped</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">prepare</span><span class="p">()</span>

<span class="c1"># do something with prepped.body</span>
<span class="c1"># do something with prepped.headers</span>

<span class="n">resp</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">prepped</span><span class="p">,</span>
    <span class="n">stream</span><span class="o">=</span><span class="n">stream</span><span class="p">,</span>
    <span class="n">verify</span><span class="o">=</span><span class="n">verify</span><span class="p">,</span>
    <span class="n">proxies</span><span class="o">=</span><span class="n">proxies</span><span class="p">,</span>
    <span class="n">cert</span><span class="o">=</span><span class="n">cert</span><span class="p">,</span>
    <span class="n">timeout</span><span class="o">=</span><span class="n">timeout</span>
<span class="p">)</span>

<span class="k">print</span><span class="p">(</span><span class="n">resp</span><span class="o">.</span><span class="n">status_code</span><span class="p">)</span>
</pre></div>
</div>
<p>Since you are not doing anything special with the <code class="docutils literal"><span class="pre">Request</span></code> object, you
prepare it immediately and modify the <code class="docutils literal"><span class="pre">PreparedRequest</span></code> object. You then
send that with the other parameters you would have sent to <code class="docutils literal"><span class="pre">requests.*</span></code> or
<code class="docutils literal"><span class="pre">Session.*</span></code>.</p>
<p>However, the above code will lose some of the advantages of having a Requests
<a class="reference internal" href="index.html#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a> object. In particular,
<a class="reference internal" href="index.html#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a>-level state such as cookies will
not get applied to your request. To get a
<a class="reference internal" href="index.html#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> with that state
applied, replace the call to <a class="reference internal" href="index.html#requests.Request.prepare" title="requests.Request.prepare"><code class="xref py py-meth docutils literal"><span class="pre">Request.prepare()</span></code></a> with a call to
<a class="reference internal" href="index.html#requests.Session.prepare_request" title="requests.Session.prepare_request"><code class="xref py py-meth docutils literal"><span class="pre">Session.prepare_request()</span></code></a>, like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>from requests import Request, Session

s = Session()
req = Request(&#39;GET&#39;,  url,
    data=data
    headers=headers
)

prepped = s.prepare_request(req)

# do something with prepped.body
# do something with prepped.headers

resp = s.send(prepped,
    stream=stream,
    verify=verify,
    proxies=proxies,
    cert=cert,
    timeout=timeout
)

print(resp.status_code)
</pre></div>
</div>
</div>
<div class="section" id="ssl-cert-verification">
<span id="verification"></span><h4>SSL Cert Verification<a class="headerlink" href="#ssl-cert-verification" title="Permalink to this headline">¶</a></h4>
<p>Requests can verify SSL certificates for HTTPS requests, just like a web browser.
To check a host&#8217;s SSL certificate, you can use the <code class="docutils literal"><span class="pre">verify</span></code> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">requests.exceptions.SSLError: hostname &#39;kennethreitz.com&#39; doesn&#39;t match either of &#39;*.herokuapp.com&#39;, &#39;herokuapp.com&#39;</span>
</pre></div>
</div>
<p>I don&#8217;t have SSL setup on this domain, so it fails. Excellent. GitHub does though:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>You can pass <code class="docutils literal"><span class="pre">verify</span></code> the path to a CA_BUNDLE file or directory with certificates of trusted CAs:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="s1">&#39;/path/to/certfile&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>This list of trusted CAs can also be specified through the <code class="docutils literal"><span class="pre">REQUESTS_CA_BUNDLE</span></code> environment variable.</p>
<p>Requests can also ignore verifying the SSL certificate if you set <code class="docutils literal"><span class="pre">verify</span></code> to False.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">verify</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>By default, <code class="docutils literal"><span class="pre">verify</span></code> is set to True. Option <code class="docutils literal"><span class="pre">verify</span></code> only applies to host certs.</p>
<p>You can also specify a local cert to use as client side certificate, as a single
file (containing the private key and the certificate) or as a tuple of both
file&#8217;s path:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">cert</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;/path/server.crt&#39;</span><span class="p">,</span> <span class="s1">&#39;/path/key&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>If you specify a wrong path or an invalid cert:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://kennethreitz.com&#39;</span><span class="p">,</span> <span class="n">cert</span><span class="o">=</span><span class="s1">&#39;/wrong_path/server.pem&#39;</span><span class="p">)</span>
<span class="go">SSLError: [Errno 336265225] _ssl.c:347: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib</span>
</pre></div>
</div>
</div>
<div class="section" id="ca-certificates">
<span id="id4"></span><h4>CA Certificates<a class="headerlink" href="#ca-certificates" title="Permalink to this headline">¶</a></h4>
<p>By default Requests bundles a set of root CAs that it trusts, sourced from the
<a class="reference external" href="#">Mozilla trust store</a>. However, these are only updated once for each Requests
version. This means that if you pin a Requests version your certificates can
become extremely out of date.</p>
<p>From Requests version 2.4.0 onwards, Requests will attempt to use certificates
from <a class="reference external" href="#">certifi</a> if it is present on the system. This allows for users to update
their trusted certificates without having to change the code that runs on their
system.</p>
<p>For the sake of security we recommend upgrading certifi frequently!</p>
</div>
<div class="section" id="body-content-workflow">
<span id="id5"></span><h4>Body Content Workflow<a class="headerlink" href="#body-content-workflow" title="Permalink to this headline">¶</a></h4>
<p>By default, when you make a request, the body of the response is downloaded
immediately. You can override this behaviour and defer downloading the response
body until you access the <a class="reference internal" href="index.html#requests.Response.content" title="requests.Response.content"><code class="xref py py-class docutils literal"><span class="pre">Response.content</span></code></a>
attribute with the <code class="docutils literal"><span class="pre">stream</span></code> parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">tarball_url</span> <span class="o">=</span> <span class="s1">&#39;https://github.com/kennethreitz/requests/tarball/master&#39;</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">tarball_url</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
<p>At this point only the response headers have been downloaded and the connection
remains open, hence allowing us to make content retrieval conditional:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="nb">int</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;content-length&#39;</span><span class="p">])</span> <span class="o">&lt;</span> <span class="n">TOO_LONG</span><span class="p">:</span>
  <span class="n">content</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">content</span>
  <span class="o">...</span>
</pre></div>
</div>
<p>You can further control the workflow by use of the <a class="reference internal" href="index.html#requests.Response.iter_content" title="requests.Response.iter_content"><code class="xref py py-class docutils literal"><span class="pre">Response.iter_content</span></code></a>
and <a class="reference internal" href="index.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><code class="xref py py-class docutils literal"><span class="pre">Response.iter_lines</span></code></a> methods.
Alternatively, you can read the undecoded body from the underlying
urllib3 <a class="reference external" href="#" title="(in urllib3 vdev)"><code class="xref py py-class docutils literal"><span class="pre">urllib3.HTTPResponse</span></code></a> at
<a class="reference internal" href="index.html#requests.Response.raw" title="requests.Response.raw"><code class="xref py py-class docutils literal"><span class="pre">Response.raw</span></code></a>.</p>
<p>If you set <code class="docutils literal"><span class="pre">stream</span></code> to <code class="docutils literal"><span class="pre">True</span></code> when making a request, Requests cannot
release the connection back to the pool unless you consume all the data or call
<a class="reference internal" href="index.html#requests.Response.close" title="requests.Response.close"><code class="xref py py-class docutils literal"><span class="pre">Response.close</span></code></a>. This can lead to
inefficiency with connections. If you find yourself partially reading request
bodies (or not reading them at all) while using <code class="docutils literal"><span class="pre">stream=True</span></code>, you should
consider using <code class="docutils literal"><span class="pre">contextlib.closing</span></code> (<a class="reference external" href="#">documented here</a>), like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>from contextlib import closing

with closing(requests.get(&#39;http://httpbin.org/get&#39;, stream=True)) as r:
    # Do things with the response here.
</pre></div>
</div>
</div>
<div class="section" id="keep-alive">
<span id="id6"></span><h4>Keep-Alive<a class="headerlink" href="#keep-alive" title="Permalink to this headline">¶</a></h4>
<p>Excellent news —&nbsp;thanks to urllib3, keep-alive is 100% automatic within a session!
Any requests that you make within a session will automatically reuse the appropriate
connection!</p>
<p>Note that connections are only released back to the pool for reuse once all body
data has been read; be sure to either set <code class="docutils literal"><span class="pre">stream</span></code> to <code class="docutils literal"><span class="pre">False</span></code> or read the
<code class="docutils literal"><span class="pre">content</span></code> property of the <code class="docutils literal"><span class="pre">Response</span></code> object.</p>
</div>
<div class="section" id="streaming-uploads">
<span id="id7"></span><h4>Streaming Uploads<a class="headerlink" href="#streaming-uploads" title="Permalink to this headline">¶</a></h4>
<p>Requests supports streaming uploads, which allow you to send large streams or
files without reading them into memory. To stream and upload, simply provide a
file-like object for your body:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;massive-body&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
    <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">&#39;http://some.url/streamed&#39;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is strongly recommended that you open files in <a class="reference external" href="#">binary mode</a>.
This is because Requests may attempt to provide the
<code class="docutils literal"><span class="pre">Content-Length</span></code> header for you, and if it does this value will
be set to the number of <em>bytes</em> in the file. Errors may occur if
you open the file in <em>text mode</em>.</p>
</div>
</div>
<div class="section" id="chunk-encoded-requests">
<span id="chunk-encoding"></span><h4>Chunk-Encoded Requests<a class="headerlink" href="#chunk-encoded-requests" title="Permalink to this headline">¶</a></h4>
<p>Requests also supports Chunked transfer encoding for outgoing and incoming requests.
To send a chunk-encoded request, simply provide a generator (or any iterator without
a length) for your body:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">gen</span><span class="p">():</span>
    <span class="k">yield</span> <span class="s1">&#39;hi&#39;</span>
    <span class="k">yield</span> <span class="s1">&#39;there&#39;</span>

<span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s1">&#39;http://some.url/chunked&#39;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">gen</span><span class="p">())</span>
</pre></div>
</div>
<p>For chunked encoded responses, it&#8217;s best to iterate over the data using
<code class="xref py py-meth docutils literal"><span class="pre">Response.iter_content()</span></code>. In
an ideal situation you&#8217;ll have set <code class="docutils literal"><span class="pre">stream=True</span></code> on the request, in which
case you can iterate chunk-by-chunk by calling <code class="docutils literal"><span class="pre">iter_content</span></code> with a chunk
size parameter of <code class="docutils literal"><span class="pre">None</span></code>. If you want to set a maximum size of the chunk,
you can set a chunk size parameter to any integer.</p>
</div>
<div class="section" id="post-multiple-multipart-encoded-files">
<span id="multipart"></span><h4>POST Multiple Multipart-Encoded Files<a class="headerlink" href="#post-multiple-multipart-encoded-files" title="Permalink to this headline">¶</a></h4>
<p>You can send multiple files in one request. For example, suppose you want to
upload image files to an HTML form with a multiple file field &#8216;images&#8217;:</p>
<blockquote>
<div>&lt;input type=&#8221;file&#8221; name=&#8221;images&#8221; multiple=&#8221;true&#8221; required=&#8221;true&#8221;/&gt;</div></blockquote>
<p>To do that, just set files to a list of tuples of (form_field_name, file_info):</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/post&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">multiple_files</span> <span class="o">=</span> <span class="p">[(</span><span class="s1">&#39;images&#39;</span><span class="p">,</span> <span class="p">(</span><span class="s1">&#39;foo.png&#39;</span><span class="p">,</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;foo.png&#39;</span><span class="p">,</span> <span class="s1">&#39;rb&#39;</span><span class="p">),</span> <span class="s1">&#39;image/png&#39;</span><span class="p">)),</span>
<span class="go">                      (&#39;images&#39;, (&#39;bar.png&#39;, open(&#39;bar.png&#39;, &#39;rb&#39;), &#39;image/png&#39;))]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">files</span><span class="o">=</span><span class="n">multiple_files</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">text</span>
<span class="go">{</span>
<span class="go">  ...</span>
<span class="go">  &#39;files&#39;: {&#39;images&#39;: &#39; ....&#39;}</span>
<span class="go">  &#39;Content-Type&#39;: &#39;multipart/form-data; boundary=3131623adb2043caaeb5538cc7aa0b3a&#39;,</span>
<span class="go">  ...</span>
<span class="go">}</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is strongly recommended that you open files in <a class="reference external" href="#">binary mode</a>.
This is because Requests may attempt to provide the
<code class="docutils literal"><span class="pre">Content-Length</span></code> header for you, and if it does this value will
be set to the number of <em>bytes</em> in the file. Errors may occur if
you open the file in <em>text mode</em>.</p>
</div>
</div>
<div class="section" id="event-hooks">
<span id="id9"></span><h4>Event Hooks<a class="headerlink" href="#event-hooks" title="Permalink to this headline">¶</a></h4>
<p>Requests has a hook system that you can use to manipulate portions of
the request process, or signal event handling.</p>
<p>Available hooks:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">response</span></code>:</dt>
<dd>The response generated from a Request.</dd>
</dl>
<p>You can assign a hook function on a per-request basis by passing a
<code class="docutils literal"><span class="pre">{hook_name:</span> <span class="pre">callback_function}</span></code> dictionary to the <code class="docutils literal"><span class="pre">hooks</span></code> request
parameter:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">hooks</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">response</span><span class="o">=</span><span class="n">print_url</span><span class="p">)</span>
</pre></div>
</div>
<p>That <code class="docutils literal"><span class="pre">callback_function</span></code> will receive a chunk of data as its first
argument.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">print_url</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
    <span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
</pre></div>
</div>
<p>If an error occurs while executing your callback, a warning is given.</p>
<p>If the callback function returns a value, it is assumed that it is to
replace the data that was passed in. If the function doesn&#8217;t return
anything, nothing else is effected.</p>
<p>Let&#8217;s print some request method arguments at runtime:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org&#39;</span><span class="p">,</span> <span class="n">hooks</span><span class="o">=</span><span class="nb">dict</span><span class="p">(</span><span class="n">response</span><span class="o">=</span><span class="n">print_url</span><span class="p">))</span>
<span class="go">http://httpbin.org</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="custom-authentication">
<span id="custom-auth"></span><h4>Custom Authentication<a class="headerlink" href="#custom-authentication" title="Permalink to this headline">¶</a></h4>
<p>Requests allows you to use specify your own authentication mechanism.</p>
<p>Any callable which is passed as the <code class="docutils literal"><span class="pre">auth</span></code> argument to a request method will
have the opportunity to modify the request before it is dispatched.</p>
<p>Authentication implementations are subclasses of <code class="docutils literal"><span class="pre">requests.auth.AuthBase</span></code>,
and are easy to define. Requests provides two common authentication scheme
implementations in <code class="docutils literal"><span class="pre">requests.auth</span></code>: <code class="docutils literal"><span class="pre">HTTPBasicAuth</span></code> and <code class="docutils literal"><span class="pre">HTTPDigestAuth</span></code>.</p>
<p>Let&#8217;s pretend that we have a web service that will only respond if the
<code class="docutils literal"><span class="pre">X-Pizza</span></code> header is set to a password value. Unlikely, but just go with it.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">AuthBase</span>

<span class="k">class</span> <span class="nc">PizzaAuth</span><span class="p">(</span><span class="n">AuthBase</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Attaches HTTP Pizza Authentication to the given Request object.&quot;&quot;&quot;</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">):</span>
        <span class="c1"># setup any auth-related data here</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">username</span> <span class="o">=</span> <span class="n">username</span>

    <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
        <span class="c1"># modify and return the request</span>
        <span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;X-Pizza&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">username</span>
        <span class="k">return</span> <span class="n">r</span>
</pre></div>
</div>
<p>Then, we can make a request using our Pizza Auth:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://pizzabin.org/admin&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">PizzaAuth</span><span class="p">(</span><span class="s1">&#39;kenneth&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="streaming-requests">
<span id="id10"></span><h4>Streaming Requests<a class="headerlink" href="#streaming-requests" title="Permalink to this headline">¶</a></h4>
<p>With <a class="reference internal" href="index.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><code class="xref py py-class docutils literal"><span class="pre">requests.Response.iter_lines()</span></code></a> you can easily
iterate over streaming APIs such as the <a class="reference external" href="#">Twitter Streaming
API</a>. Simply
set <code class="docutils literal"><span class="pre">stream</span></code> to <code class="docutils literal"><span class="pre">True</span></code> and iterate over the response with
<a class="reference internal" href="index.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><code class="xref py py-class docutils literal"><span class="pre">iter_lines()</span></code></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">json</span>
<span class="kn">import</span> <span class="nn">requests</span>

<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/stream/20&#39;</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>

<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">r</span><span class="o">.</span><span class="n">iter_lines</span><span class="p">():</span>

    <span class="c1"># filter out keep-alive new lines</span>
    <span class="k">if</span> <span class="n">line</span><span class="p">:</span>
        <span class="k">print</span><span class="p">(</span><span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">line</span><span class="p">))</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p><a class="reference internal" href="index.html#requests.Response.iter_lines" title="requests.Response.iter_lines"><code class="xref py py-class docutils literal"><span class="pre">iter_lines()</span></code></a> is not reentrant safe.
Calling this method multiple times causes some of the received data
being lost. In case you need to call it from multiple places, use
the resulting iterator object instead:</p>
<div class="last highlight-python"><div class="highlight"><pre><span></span><span class="n">lines</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">iter_lines</span><span class="p">()</span>
<span class="c1"># Save the first line for later or just skip it</span>
<span class="n">first_line</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">lines</span><span class="p">)</span>
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span>
    <span class="k">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="proxies">
<span id="id11"></span><h4>Proxies<a class="headerlink" href="#proxies" title="Permalink to this headline">¶</a></h4>
<p>If you need to use a proxy, you can configure individual requests with the
<code class="docutils literal"><span class="pre">proxies</span></code> argument to any request method:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>

<span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
  <span class="s2">&quot;http&quot;</span><span class="p">:</span> <span class="s2">&quot;http://10.10.1.10:3128&quot;</span><span class="p">,</span>
  <span class="s2">&quot;https&quot;</span><span class="p">:</span> <span class="s2">&quot;http://10.10.1.10:1080&quot;</span><span class="p">,</span>
<span class="p">}</span>

<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;http://example.org&quot;</span><span class="p">,</span> <span class="n">proxies</span><span class="o">=</span><span class="n">proxies</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also configure proxies by setting the environment variables
<code class="docutils literal"><span class="pre">HTTP_PROXY</span></code> and <code class="docutils literal"><span class="pre">HTTPS_PROXY</span></code>.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ export HTTP_PROXY=&quot;http://10.10.1.10:3128&quot;
$ export HTTPS_PROXY=&quot;http://10.10.1.10:1080&quot;
$ python
&gt;&gt;&gt; import requests
&gt;&gt;&gt; requests.get(&quot;http://example.org&quot;)
</pre></div>
</div>
<p>To use HTTP Basic Auth with your proxy, use the <cite>http://user:password&#64;host/</cite> syntax:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s2">&quot;http&quot;</span><span class="p">:</span> <span class="s2">&quot;http://user:pass@10.10.1.10:3128/&quot;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>To give a proxy for a specific scheme and host, use the
<cite>scheme://hostname</cite> form for the key.  This will match for
any request to the given scheme and exact hostname.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
  <span class="s2">&quot;http://10.20.1.128&quot;</span><span class="p">:</span> <span class="s2">&quot;http://10.10.1.10:5323&quot;</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Note that proxy URLs must include the scheme.</p>
</div>
<div class="section" id="compliance">
<span id="id12"></span><h4>Compliance<a class="headerlink" href="#compliance" title="Permalink to this headline">¶</a></h4>
<p>Requests is intended to be compliant with all relevant specifications and
RFCs where that compliance will not cause difficulties for users. This
attention to the specification can lead to some behaviour that may seem
unusual to those not familiar with the relevant specification.</p>
<div class="section" id="encodings">
<h5>Encodings<a class="headerlink" href="#encodings" title="Permalink to this headline">¶</a></h5>
<p>When you receive a response, Requests makes a guess at the encoding to
use for decoding the response when you access the <a class="reference internal" href="index.html#requests.Response.text" title="requests.Response.text"><code class="xref py py-attr docutils literal"><span class="pre">Response.text</span></code></a> attribute. Requests will first check for an
encoding in the HTTP header, and if none is present, will use <a class="reference external" href="#">chardet</a> to attempt to guess the encoding.</p>
<p>The only time Requests will not do this is if no explicit charset
is present in the HTTP headers <strong>and</strong> the <code class="docutils literal"><span class="pre">Content-Type</span></code>
header contains <code class="docutils literal"><span class="pre">text</span></code>. In this situation, <a class="reference external" href="#">RFC 2616</a> specifies
that the default charset must be <code class="docutils literal"><span class="pre">ISO-8859-1</span></code>. Requests follows the
specification in this case. If you require a different encoding, you can
manually set the <a class="reference internal" href="index.html#requests.Response.encoding" title="requests.Response.encoding"><code class="xref py py-attr docutils literal"><span class="pre">Response.encoding</span></code></a>
property, or use the raw <a class="reference internal" href="index.html#requests.Response.content" title="requests.Response.content"><code class="xref py py-attr docutils literal"><span class="pre">Response.content</span></code></a>.</p>
</div>
</div>
<div class="section" id="#">
<span id="id13"></span><h4>HTTP Verbs<a class="headerlink" href="#http-verbs" title="Permalink to this headline">¶</a></h4>
<p>Requests provides access to almost the full range of HTTP verbs: GET, OPTIONS,
HEAD, POST, PUT, PATCH and DELETE. The following provides detailed examples of
using these various verbs in Requests, using the GitHub API.</p>
<p>We will begin with the verb most commonly used: GET. HTTP GET is an idempotent
method that returns a resource from a given URL. As a result, it is the verb
you ought to use when attempting to retrieve data from a web location. An
example usage would be attempting to get information about a specific commit
from GitHub. Suppose we wanted commit <code class="docutils literal"><span class="pre">a050faf</span></code> on Requests. We would get it
like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/repos/kennethreitz/requests/git/commits/a050faf084662f3a352dd1a941f2c7c9f886d4ad&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>We should confirm that GitHub responded correctly. If it has, we want to work
out what type of content it is. Do this like so:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="o">.</span><span class="n">ok</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;content-type&#39;</span><span class="p">])</span>
<span class="gp">...</span>
<span class="go">application/json; charset=utf-8</span>
</pre></div>
</div>
<p>So, GitHub returns JSON. That&#8217;s great, we can use the <a class="reference internal" href="index.html#requests.Response.json" title="requests.Response.json"><code class="xref py py-meth docutils literal"><span class="pre">r.json</span></code></a> method to parse it into Python objects.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">commit_data</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
<span class="go">[u&#39;committer&#39;, u&#39;author&#39;, u&#39;url&#39;, u&#39;tree&#39;, u&#39;sha&#39;, u&#39;parents&#39;, u&#39;message&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="p">[</span><span class="s1">u&#39;committer&#39;</span><span class="p">])</span>
<span class="go">{u&#39;date&#39;: u&#39;2012-05-10T11:10:50-07:00&#39;, u&#39;email&#39;: u&#39;me@kennethreitz.com&#39;, u&#39;name&#39;: u&#39;Kenneth Reitz&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">commit_data</span><span class="p">[</span><span class="s1">u&#39;message&#39;</span><span class="p">])</span>
<span class="go">makin&#39; history</span>
</pre></div>
</div>
<p>So far, so simple. Well, let&#8217;s investigate the GitHub API a little bit. Now,
we could look at the documentation, but we might have a little more fun if we
use Requests instead. We can take advantage of the Requests OPTIONS verb to
see what kinds of HTTP methods are supported on the url we just used.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">500</span>
</pre></div>
</div>
<p>Uh, what? That&#8217;s unhelpful! Turns out GitHub, like many API providers, don&#8217;t
actually implement the OPTIONS method. This is an annoying oversight, but it&#8217;s
OK, we can just use the boring documentation. If GitHub had correctly
implemented OPTIONS, however, they should return the allowed methods in the
headers, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">verbs</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">options</span><span class="p">(</span><span class="s1">&#39;http://a-good-website.com/api/cats&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">verbs</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;allow&#39;</span><span class="p">])</span>
<span class="go">GET,HEAD,POST,OPTIONS</span>
</pre></div>
</div>
<p>Turning to the documentation, we see that the only other method allowed for
commits is POST, which creates a new commit. As we&#8217;re using the Requests repo,
we should probably avoid making ham-handed POSTS to it. Instead, let&#8217;s play
with the Issues feature of GitHub.</p>
<p>This documentation was added in response to Issue #482. Given that this issue
already exists, we will use it as an example. Let&#8217;s start by getting it.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/repos/kennethreitz/requests/issues/482&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">issue</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">issue</span><span class="p">[</span><span class="s1">u&#39;title&#39;</span><span class="p">])</span>
<span class="go">Feature any http verb in docs</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">issue</span><span class="p">[</span><span class="s1">u&#39;comments&#39;</span><span class="p">])</span>
<span class="go">3</span>
</pre></div>
</div>
<p>Cool, we have three comments. Let&#8217;s take a look at the last of them.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">url</span> <span class="o">+</span> <span class="s1">u&#39;/comments&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">comments</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
<span class="go">[u&#39;body&#39;, u&#39;url&#39;, u&#39;created_at&#39;, u&#39;updated_at&#39;, u&#39;user&#39;, u&#39;id&#39;]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">2</span><span class="p">][</span><span class="s1">u&#39;body&#39;</span><span class="p">])</span>
<span class="go">Probably in the &quot;advanced&quot; section</span>
</pre></div>
</div>
<p>Well, that seems like a silly place. Let&#8217;s post a comment telling the poster
that he&#8217;s silly. Who is the poster, anyway?</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">comments</span><span class="p">[</span><span class="mi">2</span><span class="p">][</span><span class="s1">u&#39;user&#39;</span><span class="p">][</span><span class="s1">u&#39;login&#39;</span><span class="p">])</span>
<span class="go">kennethreitz</span>
</pre></div>
</div>
<p>OK, so let&#8217;s tell this Kenneth guy that we think this example should go in the
quickstart guide instead. According to the GitHub API doc, the way to do this
is to POST to the thread. Let&#8217;s do it.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">body</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s2">u&quot;body&quot;</span><span class="p">:</span> <span class="s2">u&quot;Sounds great! I&#39;ll get right on it!&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s2">u&quot;https://api.github.com/repos/kennethreitz/requests/issues/482/comments&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">404</span>
</pre></div>
</div>
<p>Huh, that&#8217;s weird. We probably need to authenticate. That&#8217;ll be a pain, right?
Wrong. Requests makes it easy to use many forms of authentication, including
the very common Basic Auth.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">auth</span> <span class="o">=</span> <span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="s1">&#39;fake@example.com&#39;</span><span class="p">,</span> <span class="s1">&#39;not_a_real_password&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">201</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">content</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">content</span><span class="p">[</span><span class="s1">u&#39;body&#39;</span><span class="p">])</span>
<span class="go">Sounds great! I&#39;ll get right on it.</span>
</pre></div>
</div>
<p>Brilliant. Oh, wait, no! I meant to add that it would take me a while, because
I had to go feed my cat. If only I could edit this comment! Happily, GitHub
allows us to use another HTTP verb, PATCH, to edit this comment. Let&#8217;s do
that.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">content</span><span class="p">[</span><span class="s2">u&quot;id&quot;</span><span class="p">])</span>
<span class="go">5804413</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">body</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span><span class="s2">u&quot;body&quot;</span><span class="p">:</span> <span class="s2">u&quot;Sounds great! I&#39;ll get right on it once I feed my cat.&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s2">u&quot;https://api.github.com/repos/kennethreitz/requests/issues/comments/5804413&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="n">body</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">200</span>
</pre></div>
</div>
<p>Excellent. Now, just to torture this Kenneth guy, I&#8217;ve decided to let him
sweat and not tell him that I&#8217;m working on this. That means I want to delete
this comment. GitHub lets us delete comments using the incredibly aptly named
DELETE method. Let&#8217;s get rid of it.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">status_code</span>
<span class="go">204</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;status&#39;</span><span class="p">]</span>
<span class="go">&#39;204 No Content&#39;</span>
</pre></div>
</div>
<p>Excellent. All gone. The last thing I want to know is how much of my ratelimit
I&#8217;ve used. Let&#8217;s find out. GitHub sends that information in the headers, so
rather than download the whole page I&#8217;ll send a HEAD request to get the
headers.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span><span class="p">(</span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">)</span>
<span class="gp">...</span>
<span class="go">&#39;x-ratelimit-remaining&#39;: &#39;4995&#39;</span>
<span class="go">&#39;x-ratelimit-limit&#39;: &#39;5000&#39;</span>
<span class="gp">...</span>
</pre></div>
</div>
<p>Excellent. Time to write a Python program that abuses the GitHub API in all
kinds of exciting ways, 4995 more times.</p>
</div>
<div class="section" id="link-headers">
<span id="id14"></span><h4>Link Headers<a class="headerlink" href="#link-headers" title="Permalink to this headline">¶</a></h4>
<p>Many HTTP APIs feature Link headers. They make APIs more self describing and
discoverable.</p>
<p>GitHub uses these for <a class="reference external" href="#">pagination</a>
in their API, for example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;https://api.github.com/users/kennethreitz/repos?page=1&amp;per_page=10&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">head</span><span class="p">(</span><span class="n">url</span><span class="o">=</span><span class="n">url</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">headers</span><span class="p">[</span><span class="s1">&#39;link&#39;</span><span class="p">]</span>
<span class="go">&#39;&lt;https://api.github.com/users/kennethreitz/repos?page=2&amp;per_page=10&gt;; rel=&quot;next&quot;, &lt;https://api.github.com/users/kennethreitz/repos?page=6&amp;per_page=10&gt;; rel=&quot;last&quot;&#39;</span>
</pre></div>
</div>
<p>Requests will automatically parse these link headers and make them easily consumable:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">links</span><span class="p">[</span><span class="s2">&quot;next&quot;</span><span class="p">]</span>
<span class="go">{&#39;url&#39;: &#39;https://api.github.com/users/kennethreitz/repos?page=2&amp;per_page=10&#39;, &#39;rel&#39;: &#39;next&#39;}</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span><span class="o">.</span><span class="n">links</span><span class="p">[</span><span class="s2">&quot;last&quot;</span><span class="p">]</span>
<span class="go">{&#39;url&#39;: &#39;https://api.github.com/users/kennethreitz/repos?page=7&amp;per_page=10&#39;, &#39;rel&#39;: &#39;last&#39;}</span>
</pre></div>
</div>
</div>
<div class="section" id="transport-adapters">
<span id="id15"></span><h4>Transport Adapters<a class="headerlink" href="#transport-adapters" title="Permalink to this headline">¶</a></h4>
<p>As of v1.0.0, Requests has moved to a modular internal design. Part of the
reason this was done was to implement Transport Adapters, originally
<a class="reference external" href="#">described here</a>. Transport Adapters provide a mechanism to define interaction
methods for an HTTP service. In particular, they allow you to apply per-service
configuration.</p>
<p>Requests ships with a single Transport Adapter, the <a class="reference internal" href="index.html#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>. This adapter provides the default Requests
interaction with HTTP and HTTPS using the powerful <a class="reference external" href="#">urllib3</a> library. Whenever
a Requests <a class="reference internal" href="index.html#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a> is initialized, one of these is
attached to the <a class="reference internal" href="index.html#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a> object for HTTP, and one
for HTTPS.</p>
<p>Requests enables users to create and use their own Transport Adapters that
provide specific functionality. Once created, a Transport Adapter can be
mounted to a Session object, along with an indication of which web services
it should apply to.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">mount</span><span class="p">(</span><span class="s1">&#39;http://www.github.com&#39;</span><span class="p">,</span> <span class="n">MyAdapter</span><span class="p">())</span>
</pre></div>
</div>
<p>The mount call registers a specific instance of a Transport Adapter to a
prefix. Once mounted, any HTTP request made using that session whose URL starts
with the given prefix will use the given Transport Adapter.</p>
<p>Many of the details of implementing a Transport Adapter are beyond the scope of
this documentation, but take a look at the next example for a simple SSL use-
case. For more than that, you might look at subclassing
<code class="docutils literal"><span class="pre">requests.adapters.BaseAdapter</span></code>.</p>
<div class="section" id="example-specific-ssl-version">
<h5>Example: Specific SSL Version<a class="headerlink" href="#example-specific-ssl-version" title="Permalink to this headline">¶</a></h5>
<p>The Requests team has made a specific choice to use whatever SSL version is
default in the underlying library (<a class="reference external" href="#">urllib3</a>). Normally this is fine, but from
time to time, you might find yourself needing to connect to a service-endpoint
that uses a version that isn&#8217;t compatible with the default.</p>
<p>You can use Transport Adapters for this by taking most of the existing
implementation of HTTPAdapter, and adding a parameter <em>ssl_version</em> that gets
passed-through to <cite>urllib3</cite>. We&#8217;ll make a TA that instructs the library to use
SSLv3:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">ssl</span>

<span class="kn">from</span> <span class="nn">requests.adapters</span> <span class="kn">import</span> <span class="n">HTTPAdapter</span>
<span class="kn">from</span> <span class="nn">requests.packages.urllib3.poolmanager</span> <span class="kn">import</span> <span class="n">PoolManager</span>


<span class="k">class</span> <span class="nc">Ssl3HttpAdapter</span><span class="p">(</span><span class="n">HTTPAdapter</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;&quot;Transport adapter&quot; that allows us to use SSLv3.&quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="nf">init_poolmanager</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">connections</span><span class="p">,</span> <span class="n">maxsize</span><span class="p">,</span> <span class="n">block</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">poolmanager</span> <span class="o">=</span> <span class="n">PoolManager</span><span class="p">(</span><span class="n">num_pools</span><span class="o">=</span><span class="n">connections</span><span class="p">,</span>
                                       <span class="n">maxsize</span><span class="o">=</span><span class="n">maxsize</span><span class="p">,</span>
                                       <span class="n">block</span><span class="o">=</span><span class="n">block</span><span class="p">,</span>
                                       <span class="n">ssl_version</span><span class="o">=</span><span class="n">ssl</span><span class="o">.</span><span class="n">PROTOCOL_SSLv3</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="blocking-or-non-blocking">
<span id="blocking-or-nonblocking"></span><h4>Blocking Or Non-Blocking?<a class="headerlink" href="#blocking-or-non-blocking" title="Permalink to this headline">¶</a></h4>
<p>With the default Transport Adapter in place, Requests does not provide any kind
of non-blocking IO. The <a class="reference internal" href="index.html#requests.Response.content" title="requests.Response.content"><code class="xref py py-attr docutils literal"><span class="pre">Response.content</span></code></a>
property will block until the entire response has been downloaded. If
you require more granularity, the streaming features of the library (see
<a class="reference internal" href="#streaming-requests"><span>Streaming Requests</span></a>) allow you to retrieve smaller quantities of the
response at a time. However, these calls will still block.</p>
<p>If you are concerned about the use of blocking IO, there are lots of projects
out there that combine Requests with one of Python&#8217;s asynchronicity frameworks.
Two excellent examples are <a class="reference external" href="#">grequests</a> and <a class="reference external" href="#">requests-futures</a>.</p>
</div>
<div class="section" id="timeouts">
<span id="id16"></span><h4>Timeouts<a class="headerlink" href="#timeouts" title="Permalink to this headline">¶</a></h4>
<p>Most requests to external servers should have a timeout attached, in case the
server is not responding in a timely manner. Without a timeout, your code may
hang for minutes or more.</p>
<p>The <strong>connect</strong> timeout is the number of seconds Requests will wait for your
client to establish a connection to a remote machine (corresponding to the
<a class="reference external" href="#">connect()</a>) call on the socket. It&#8217;s a good practice to set connect timeouts
to slightly larger than a multiple of 3, which is the default <a class="reference external" href="#">TCP packet
retransmission window</a>.</p>
<p>Once your client has connected to the server and sent the HTTP request, the
<strong>read</strong> timeout is the number of seconds the client will wait for the server
to send a response. (Specifically, it&#8217;s the number of seconds that the client
will wait <em>between</em> bytes sent from the server. In 99.9% of cases, this is the
time before the server sends the first byte).</p>
<p>If you specify a single value for the timeout, like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
</pre></div>
</div>
<p>The timeout value will be applied to both the <code class="docutils literal"><span class="pre">connect</span></code> and the <code class="docutils literal"><span class="pre">read</span></code>
timeouts. Specify a tuple if you would like to set the values separately:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="p">(</span><span class="mf">3.05</span><span class="p">,</span> <span class="mi">27</span><span class="p">))</span>
</pre></div>
</div>
<p>If the remote server is very slow, you can tell Requests to wait forever for
a response, by passing None as a timeout value and then retrieving a cup of
coffee.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com&#39;</span><span class="p">,</span> <span class="n">timeout</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<span id="document-user/authentication"></span><div class="section" id="authentication">
<span id="id1"></span><h3>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h3>
<p>This document discusses using various kinds of authentication with Requests.</p>
<p>Many web services require authentication, and there are many different types.
Below, we outline various forms of authentication available in Requests, from
the simple to the complex.</p>
<div class="section" id="basic-authentication">
<h4>Basic Authentication<a class="headerlink" href="#basic-authentication" title="Permalink to this headline">¶</a></h4>
<p>Many web services that require authentication accept HTTP Basic Auth. This is
the simplest kind, and Requests supports it straight out of the box.</p>
<p>Making requests with HTTP Basic Auth is very simple:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/user&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="s1">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>In fact, HTTP Basic Auth is so common that Requests provides a handy shorthand
for using it:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://api.github.com/user&#39;</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="s1">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>Providing the credentials in a tuple like this is exactly the same as the
<code class="docutils literal"><span class="pre">HTTPBasicAuth</span></code> example above.</p>
<div class="section" id="netrc-authentication">
<h5>netrc Authentication<a class="headerlink" href="#netrc-authentication" title="Permalink to this headline">¶</a></h5>
<p>If no authentication method is given with the <code class="docutils literal"><span class="pre">auth</span></code> argument, Requests will
attempt to get the authentication credentials for the URL&#8217;s hostname from the
user&#8217;s netrc file.</p>
<p>If credentials for the hostname are found, the request is sent with HTTP Basic
Auth.</p>
</div>
</div>
<div class="section" id="digest-authentication">
<h4>Digest Authentication<a class="headerlink" href="#digest-authentication" title="Permalink to this headline">¶</a></h4>
<p>Another very popular form of HTTP Authentication is Digest Authentication,
and Requests supports this out of the box as well:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPDigestAuth</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/digest-auth/auth/user/pass&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">HTTPDigestAuth</span><span class="p">(</span><span class="s1">&#39;user&#39;</span><span class="p">,</span> <span class="s1">&#39;pass&#39;</span><span class="p">))</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="oauth-1-authentication">
<h4>OAuth 1 Authentication<a class="headerlink" href="#oauth-1-authentication" title="Permalink to this headline">¶</a></h4>
<p>A common form of authentication for several web APIs is OAuth. The <code class="docutils literal"><span class="pre">requests-oauthlib</span></code>
library allows Requests users to easily make OAuth authenticated requests:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">requests_oauthlib</span> <span class="kn">import</span> <span class="n">OAuth1</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;https://api.twitter.com/1.1/account/verify_credentials.json&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">auth</span> <span class="o">=</span> <span class="n">OAuth1</span><span class="p">(</span><span class="s1">&#39;YOUR_APP_KEY&#39;</span><span class="p">,</span> <span class="s1">&#39;YOUR_APP_SECRET&#39;</span><span class="p">,</span>
<span class="go">                  &#39;USER_OAUTH_TOKEN&#39;, &#39;USER_OAUTH_TOKEN_SECRET&#39;)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">auth</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>For more information on how to OAuth flow works, please see the official <a class="reference external" href="#">OAuth</a> website.
For examples and documentation on requests-oauthlib, please see the <a class="reference external" href="#">requests_oauthlib</a>
repository on GitHub</p>
</div>
<div class="section" id="other-authentication">
<h4>Other Authentication<a class="headerlink" href="#other-authentication" title="Permalink to this headline">¶</a></h4>
<p>Requests is designed to allow other forms of authentication to be easily and
quickly plugged in. Members of the open-source community frequently write
authentication handlers for more complicated or less commonly-used forms of
authentication. Some of the best have been brought together under the
<a class="reference external" href="#">Requests organization</a>, including:</p>
<ul class="simple">
<li><a class="reference external" href="#">Kerberos</a></li>
<li><a class="reference external" href="#">NTLM</a></li>
</ul>
<p>If you want to use any of these forms of authentication, go straight to their
GitHub page and follow the instructions.</p>
</div>
<div class="section" id="new-forms-of-authentication">
<h4>New Forms of Authentication<a class="headerlink" href="#new-forms-of-authentication" title="Permalink to this headline">¶</a></h4>
<p>If you can&#8217;t find a good implementation of the form of authentication you
want, you can implement it yourself. Requests makes it easy to add your own
forms of authentication.</p>
<p>To do so, subclass <a class="reference internal" href="index.html#requests.auth.AuthBase" title="requests.auth.AuthBase"><code class="xref py py-class docutils literal"><span class="pre">AuthBase</span></code></a> and implement the
<code class="docutils literal"><span class="pre">__call__()</span></code> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyAuth</span><span class="p">(</span><span class="n">requests</span><span class="o">.</span><span class="n">auth</span><span class="o">.</span><span class="n">AuthBase</span><span class="p">):</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
<span class="gp">... </span>        <span class="c1"># Implement my authentication</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="n">r</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">url</span> <span class="o">=</span> <span class="s1">&#39;http://httpbin.org/get&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">auth</span><span class="o">=</span><span class="n">MyAuth</span><span class="p">())</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>When an authentication handler is attached to a request,
it is called during request setup. The <code class="docutils literal"><span class="pre">__call__</span></code> method must therefore do
whatever is required to make the authentication work. Some forms of
authentication will additionally add hooks to provide further functionality.</p>
<p>Further examples can be found under the <a class="reference external" href="#">Requests organization</a> and in the
<code class="docutils literal"><span class="pre">auth.py</span></code> file.</p>
</div>
</div>
</div>
</div>
<div class="section" id="community-guide">
<h2>Community Guide<a class="headerlink" href="#community-guide" title="Permalink to this headline">¶</a></h2>
<p>This part of the documentation, which is mostly prose, details the
Requests ecosystem and community.</p>
<div class="toctree-wrapper compound">
<span id="document-community/faq"></span><div class="section" id="frequently-asked-questions">
<span id="faq"></span><h3>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h3>
<p>This part of the documentation answers common questions about Requests.</p>
<div class="section" id="encoded-data">
<h4>Encoded Data?<a class="headerlink" href="#encoded-data" title="Permalink to this headline">¶</a></h4>
<p>Requests automatically decompresses gzip-encoded responses, and does
its best to decode response content to unicode when possible.</p>
<p>You can get direct access to the raw response (and even the socket),
if needed as well.</p>
</div>
<div class="section" id="custom-user-agents">
<h4>Custom User-Agents?<a class="headerlink" href="#custom-user-agents" title="Permalink to this headline">¶</a></h4>
<p>Requests allows you to easily override User-Agent strings, along with
any other HTTP Header.</p>
</div>
<div class="section" id="why-not-httplib2">
<h4>Why not Httplib2?<a class="headerlink" href="#why-not-httplib2" title="Permalink to this headline">¶</a></h4>
<p>Chris Adams gave an excellent summary on
<a class="reference external" href="#">Hacker News</a>:</p>
<blockquote>
<div><p>httplib2 is part of why you should use requests: it&#8217;s far more respectable
as a client but not as well documented and it still takes way too much code
for basic operations. I appreciate what httplib2 is trying to do, that
there&#8217;s a ton of hard low-level annoyances in building a modern HTTP
client, but really, just use requests instead. Kenneth Reitz is very
motivated and he gets the degree to which simple things should be simple
whereas httplib2 feels more like an academic exercise than something
people should use to build production systems[1].</p>
<p>Disclosure: I&#8217;m listed in the requests AUTHORS file but can claim credit
for, oh, about 0.0001% of the awesomeness.</p>
<p>1. <a class="reference external" href="#">http://code.google.com/p/httplib2/issues/detail?id=96</a> is a good example:
an annoying bug which affect many people, there was a fix available for
months, which worked great when I applied it in a fork and pounded a couple
TB of data through it, but it took over a year to make it into trunk and
even longer to make it onto PyPI where any other project which required &#8221;
httplib2&#8221; would get the working version.</p>
</div></blockquote>
</div>
<div class="section" id="python-3-support">
<h4>Python 3 Support?<a class="headerlink" href="#python-3-support" title="Permalink to this headline">¶</a></h4>
<p>Yes! Here&#8217;s a list of Python platforms that are officially
supported:</p>
<ul class="simple">
<li>Python 2.6</li>
<li>Python 2.7</li>
<li>Python 3.1</li>
<li>Python 3.2</li>
<li>Python 3.3</li>
<li>Python 3.4</li>
<li>PyPy 1.9</li>
<li>PyPy 2.2</li>
</ul>
</div>
<div class="section" id="what-are-hostname-doesn-t-match-errors">
<h4>What are &#8220;hostname doesn&#8217;t match&#8221; errors?<a class="headerlink" href="#what-are-hostname-doesn-t-match-errors" title="Permalink to this headline">¶</a></h4>
<p>These errors occur when <a class="reference internal" href="index.html#verification"><span>SSL certificate verification</span></a>
fails to match the certificate the server responds with to the hostname
Requests thinks it&#8217;s contacting. If you&#8217;re certain the server&#8217;s SSL setup is
correct (for example, because you can visit the site with your browser) and
you&#8217;re using Python 2.6 or 2.7, a possible explanation is that you need
Server-Name-Indication.</p>
<p><a class="reference external" href="#">Server-Name-Indication</a>, or SNI, is an official extension to SSL where the
client tells the server what hostname it is contacting. This is important
when servers are using <a class="reference external" href="#">Virtual Hosting</a>. When such servers are hosting
more than one SSL site they need to be able to return the appropriate
certificate based on the hostname the client is connecting to.</p>
<p>Python3 and Python 2.7.9+ include native support for SNI in their SSL modules.
For information on using SNI with Requests on Python &lt; 2.7.9 refer to this
<a class="reference external" href="#">Stack Overflow answer</a>.</p>
</div>
</div>
<span id="document-community/recommended"></span><div class="section" id="recommended-packages-and-extensions">
<span id="recommended"></span><h3>Recommended Packages and Extensions<a class="headerlink" href="#recommended-packages-and-extensions" title="Permalink to this headline">¶</a></h3>
<p>Requests has a great variety of powerful and useful third-party extensions.
This page provides an overview of some of the best of them.</p>
<div class="section" id="certifi-ca-bundle">
<h4>Certifi CA Bundle<a class="headerlink" href="#certifi-ca-bundle" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">Certifi</a> is a carefully curated collection of Root Certificates for
validating the trustworthiness of SSL certificates while verifying the
identity of TLS hosts. It has been extracted from the Requests project.</p>
</div>
<div class="section" id="cachecontrol">
<h4>CacheControl<a class="headerlink" href="#cachecontrol" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">CacheControl</a> is an extension that adds a full HTTP cache to Requests. This
makes your web requests substantially more efficient, and should be used
whenever you&#8217;re making a lot of web requests.</p>
</div>
<div class="section" id="requests-toolbelt">
<h4>Requests-Toolbelt<a class="headerlink" href="#requests-toolbelt" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">Requests-Toolbelt</a> is a collection of utilities that some users of Requests may desire,
but do not belong in Requests proper. This library is actively maintained
by members of the Requests core team, and reflects the functionality most
requested by users within the community.</p>
</div>
<div class="section" id="requests-oauthlib">
<h4>Requests-OAuthlib<a class="headerlink" href="#requests-oauthlib" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">requests-oauthlib</a> makes it possible to do the OAuth dance from Requests
automatically. This is useful for the large number of websites that use OAuth
to provide authentication. It also provides a lot of tweaks that handle ways
that specific OAuth providers differ from the standard specifications.</p>
</div>
<div class="section" id="betamax">
<h4>Betamax<a class="headerlink" href="#betamax" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">Betamax</a> records your HTTP interactions so the NSA does not have to.
A VCR imitation designed only for Python-Requests.</p>
</div>
</div>
<span id="document-community/out-there"></span><div class="section" id="integrations">
<h3>Integrations<a class="headerlink" href="#integrations" title="Permalink to this headline">¶</a></h3>
<div class="section" id="scraperwiki">
<h4>ScraperWiki<a class="headerlink" href="#scraperwiki" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">ScraperWiki</a> is an excellent service that allows
you to run Python, Ruby, and PHP scraper scripts on the web. Now, Requests
v0.6.1 is available to use in your scrapers!</p>
<p>To give it a try, simply:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
</pre></div>
</div>
</div>
<div class="section" id="python-for-ios">
<h4>Python for iOS<a class="headerlink" href="#python-for-ios" title="Permalink to this headline">¶</a></h4>
<p>Requests is built into the wonderful <a class="reference external" href="#">Python for iOS</a> runtime!</p>
<p>To give it a try, simply:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="articles-talks">
<h3>Articles &amp; Talks<a class="headerlink" href="#articles-talks" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><a class="reference external" href="#">Python for the Web</a> teaches how to use Python to interact with the web, using Requests.</li>
<li><a class="reference external" href="#">Daniel Greenfeld&#8217;s Review of Requests</a></li>
<li><a class="reference external" href="#">My &#8216;Python for Humans&#8217; talk</a> ( <a class="reference external" href="#">audio</a> )</li>
<li><a class="reference external" href="#">Issac Kelly&#8217;s &#8216;Consuming Web APIs&#8217; talk</a></li>
<li><a class="reference external" href="#">Blog post about Requests via Yum</a></li>
<li><a class="reference external" href="#">Russian blog post introducing Requests</a></li>
<li><a class="reference external" href="#">Sending JSON in Requests</a></li>
</ul>
</div>
<span id="document-community/support"></span><div class="section" id="support">
<span id="id1"></span><h3>Support<a class="headerlink" href="#support" title="Permalink to this headline">¶</a></h3>
<p>If you have questions or issues about Requests, there are several options:</p>
<div class="section" id="stackoverflow">
<h4>StackOverflow<a class="headerlink" href="#stackoverflow" title="Permalink to this headline">¶</a></h4>
<p>If your question does not contain sensitive (possibly proprietary)
information or can be properly anonymized, please ask a question on
<a class="reference external" href="#">StackOverflow</a>
and use the tag <code class="docutils literal"><span class="pre">python-requests</span></code>.</p>
</div>
<div class="section" id="send-a-tweet">
<h4>Send a Tweet<a class="headerlink" href="#send-a-tweet" title="Permalink to this headline">¶</a></h4>
<p>If your question is less than 140 characters, feel free to send a tweet to
<a class="reference external" href="#">&#64;kennethreitz</a>,
<a class="reference external" href="#">&#64;sigmavirus24</a>, or
<a class="reference external" href="#">&#64;lukasaoz</a>.</p>
</div>
<div class="section" id="file-an-issue">
<h4>File an Issue<a class="headerlink" href="#file-an-issue" title="Permalink to this headline">¶</a></h4>
<p>If you notice some unexpected behaviour in Requests, or want to see support
for a new feature,
<a class="reference external" href="#">file an issue on GitHub</a>.</p>
</div>
<div class="section" id="e-mail">
<h4>E-mail<a class="headerlink" href="#e-mail" title="Permalink to this headline">¶</a></h4>
<p>I&#8217;m more than happy to answer any personal or in-depth questions about
Requests. Feel free to email
<a class="reference external" href="mailto:requests&#37;&#52;&#48;kennethreitz&#46;com">requests<span>&#64;</span>kennethreitz<span>&#46;</span>com</a>.</p>
</div>
<div class="section" id="irc">
<h4>IRC<a class="headerlink" href="#irc" title="Permalink to this headline">¶</a></h4>
<p>The official Freenode channel for Requests is
<a class="reference external" href="irc://irc.freenode.net/python-requests">#python-requests</a></p>
<p>The core developers of requests are on IRC throughout the day.
You can find them in <code class="docutils literal"><span class="pre">#python-requests</span></code> as:</p>
<ul class="simple">
<li>kennethreitz</li>
<li>lukasa</li>
<li>sigmavirus24</li>
</ul>
</div>
</div>
<span id="document-community/vulnerabilities"></span><div class="section" id="vulnerability-disclosure">
<h3>Vulnerability Disclosure<a class="headerlink" href="#vulnerability-disclosure" title="Permalink to this headline">¶</a></h3>
<p>If you think you have found a potential security vulnerability in requests,
please email <a class="reference external" href="mailto:graffatcolmingov&#37;&#52;&#48;gmail&#46;com">sigmavirus24</a> and
<a class="reference external" href="mailto:cory&#37;&#52;&#48;lukasa&#46;co&#46;uk">Lukasa</a> directly. <strong>Do not file a public issue.</strong></p>
<p>Our PGP Key fingerprints are:</p>
<ul class="simple">
<li>0161 BB7E B208 B5E0 4FDC  9F81 D9DA 0A04 9113 F853 (&#64;sigmavirus24)</li>
<li>90DC AE40 FEA7 4B14 9B70  662D F25F 2144 EEC1 373D (&#64;lukasa)</li>
</ul>
<p>If English is not your first language, please try to describe the problem and
its impact to the best of your ability. For greater detail, please use your
native language and we will try our best to translate it using online services.</p>
<p>Please also include the code you used to find the problem and the shortest
amount of code necessary to reproduce it.</p>
<p>Please do not disclose this to anyone else. We will retrieve a CVE identifier
if necessary and give you full credit under whatever name or alias you provide.
We will only request an identifier when we have a fix and can publish it in a
release.</p>
<p>We will respect your privacy and will only publicize your involvement if you
grant us permission.</p>
<div class="section" id="process">
<h4>Process<a class="headerlink" href="#process" title="Permalink to this headline">¶</a></h4>
<p>This following information discusses the process the requests project follows
in response to vulnerability disclosures. If you are disclosing a
vulnerability, this section of the documentation lets you know how we will
respond to your disclosure.</p>
<div class="section" id="timeline">
<h5>Timeline<a class="headerlink" href="#timeline" title="Permalink to this headline">¶</a></h5>
<p>When you report an issue, one of the project members will respond to you within
two days <em>at the outside</em>. In most cases responses will be faster, usually
within 12 hours. This initial response will at the very least confirm receipt
of the report.</p>
<p>If we were able to rapidly reproduce the issue, the initial response will also
contain confirmation of the issue. If we are not, we will often ask for more
information about the reproduction scenario.</p>
<p>Our goal is to have a fix for any vulnerability released within two weeks of
the initial disclosure. This may potentially involve shipping an interim
release that simply disables function while a more mature fix can be prepared,
but will in the vast majority of cases mean shipping a complete release as soon
as possible.</p>
<p>Throughout the fix process we will keep you up to speed with how the fix is
progressing. Once the fix is prepared, we will notify you that we believe we
have a fix. Often we will ask you to confirm the fix resolves the problem in
your environment, especially if we are not confident of our reproduction
scenario.</p>
<p>At this point, we will prepare for the release. We will obtain a CVE number
if one is required, providing you with full credit for the discovery. We will
also decide on a planned release date, and let you know when it is. This
release date will <em>always</em> be on a weekday.</p>
<p>At this point we will reach out to our major downstream packagers to notify
them of an impending security-related patch so they can make arrangements. In
addition, these packagers will be provided with the intended patch ahead of
time, to ensure that they are able to promptly release their downstream
packages. Currently the list of people we actively contact <em>ahead of a public
release</em> is:</p>
<ul class="simple">
<li>Ralph Bean, Red Hat (&#64;ralphbean)</li>
<li>Daniele Tricoli, Debian (&#64;eriol)</li>
</ul>
<p>We will notify these individuals at least a week ahead of our planned release
date to ensure that they have sufficient time to prepare. If you believe you
should be on this list, please let one of the maintainers know at one of the
email addresses at the top of this article.</p>
<p>On release day, we will push the patch to our public repository, along with an
updated changelog that describes the issue and credits you. We will then issue
a PyPI release containing the patch.</p>
<p>At this point, we will publicise the release. This will involve mails to
mailing lists, Tweets, and all other communication mechanisms available to the
core team.</p>
<p>We will also explicitly mention which commits contain the fix to make it easier
for other distributors and users to easily patch their own versions of requests
if upgrading is not an option.</p>
</div>
</div>
<div class="section" id="previous-cves">
<h4>Previous CVEs<a class="headerlink" href="#previous-cves" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Fixed in 2.6.0<ul>
<li><a class="reference external" href="#">CVE 2015-2296</a>,
reported by Matthew Daley of <a class="reference external" href="#">BugFuzz</a>.</li>
</ul>
</li>
<li>Fixed in 2.3.0<ul>
<li><a class="reference external" href="#">CVE 2014-1829</a></li>
<li><a class="reference external" href="#">CVE 2014-1830</a></li>
</ul>
</li>
</ul>
</div>
</div>
<span id="document-community/updates"></span><div class="section" id="community-updates">
<span id="updates"></span><h3>Community Updates<a class="headerlink" href="#community-updates" title="Permalink to this headline">¶</a></h3>
<p>If you&#8217;d like to stay up to date on the community and development of Requests,
there are several options:</p>
<div class="section" id="github">
<h4>GitHub<a class="headerlink" href="#github" title="Permalink to this headline">¶</a></h4>
<p>The best way to track the development of Requests is through
<a class="reference external" href="#">the GitHub repo</a>.</p>
</div>
<div class="section" id="twitter">
<h4>Twitter<a class="headerlink" href="#twitter" title="Permalink to this headline">¶</a></h4>
<p>The author, Kenneth Reitz, often tweets about new features and releases of Requests.</p>
<p>Follow <a class="reference external" href="#">&#64;kennethreitz</a> for updates.</p>
</div>
</div>
<div class="section" id="release-and-version-history">
<h3>Release and Version History<a class="headerlink" href="#release-and-version-history" title="Permalink to this headline">¶</a></h3>
<div class="section" id="release-history">
<h4>Release History<a class="headerlink" href="#release-history" title="Permalink to this headline">¶</a></h4>
<div class="section" id="id1">
<h5>2.9.1 (2015-12-21)<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Resolve regression introduced in 2.9.0 that made it impossible to send binary
strings as bodies in Python 3.</li>
<li>Fixed errors when calculating cookie expiration dates in certain locales.</li>
</ul>
<p><strong>Miscellaneous</strong></p>
<ul class="simple">
<li>Updated bundled urllib3 to 1.13.1.</li>
</ul>
</div>
<div class="section" id="id2">
<h5>2.9.0 (2015-12-15)<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h5>
<p><strong>Minor Improvements</strong> (Backwards compatible)</p>
<ul class="simple">
<li>The <code class="docutils literal"><span class="pre">verify</span></code> keyword argument now supports being passed a path to a
directory of CA certificates, not just a single-file bundle.</li>
<li>Warnings are now emitted when sending files opened in text mode.</li>
<li>Added the 511 Network Authentication Required status code to the status code
registry.</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>For file-like objects that are not seeked to the very beginning, we now
send the content length for the number of bytes we will actually read, rather
than the total size of the file, allowing partial file uploads.</li>
<li>When uploading file-like objects, if they are empty or have no obvious
content length we set <code class="docutils literal"><span class="pre">Transfer-Encoding:</span> <span class="pre">chunked</span></code> rather than
<code class="docutils literal"><span class="pre">Content-Length:</span> <span class="pre">0</span></code>.</li>
<li>We correctly receive the response in buffered mode when uploading chunked
bodies.</li>
<li>We now handle being passed a query string as a bytestring on Python 3, by
decoding it as UTF-8.</li>
<li>Sessions are now closed in all cases (exceptional and not) when using the
functional API rather than leaking and waiting for the garbage collector to
clean them up.</li>
<li>Correctly handle digest auth headers with a malformed <code class="docutils literal"><span class="pre">qop</span></code> directive that
contains no token, by treating it the same as if no <code class="docutils literal"><span class="pre">qop</span></code> directive was
provided at all.</li>
<li>Minor performance improvements when removing specific cookies by name.</li>
</ul>
<p><strong>Miscellaneous</strong></p>
<ul class="simple">
<li>Updated urllib3 to 1.13.</li>
</ul>
</div>
<div class="section" id="id3">
<h5>2.8.1 (2015-10-13)<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Update certificate bundle to match <code class="docutils literal"><span class="pre">certifi</span></code> 2015.9.6.2&#8217;s weak certificate
bundle.</li>
<li>Fix a bug in 2.8.0 where requests would raise <code class="docutils literal"><span class="pre">ConnectTimeout</span></code> instead of
<code class="docutils literal"><span class="pre">ConnectionError</span></code></li>
<li>When using the PreparedRequest flow, requests will now correctly respect the
<code class="docutils literal"><span class="pre">json</span></code> parameter. Broken in 2.8.0.</li>
<li>When using the PreparedRequest flow, requests will now correctly handle a
Unicode-string method name on Python 2. Broken in 2.8.0.</li>
</ul>
</div>
<div class="section" id="id4">
<h5>2.8.0 (2015-10-05)<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
<p><strong>Minor Improvements</strong> (Backwards Compatible)</p>
<ul class="simple">
<li>Requests now supports per-host proxies. This allows the <code class="docutils literal"><span class="pre">proxies</span></code>
dictionary to have entries of the form
<code class="docutils literal"><span class="pre">{'&lt;scheme&gt;://&lt;hostname&gt;':</span> <span class="pre">'&lt;proxy&gt;'}</span></code>. Host-specific proxies will be used
in preference to the previously-supported scheme-specific ones, but the
previous syntax will continue to work.</li>
<li><code class="docutils literal"><span class="pre">Response.raise_for_status</span></code> now prints the URL that failed as part of the
exception message.</li>
<li><code class="docutils literal"><span class="pre">requests.utils.get_netrc_auth</span></code> now takes an <code class="docutils literal"><span class="pre">raise_errors</span></code> kwarg,
defaulting to <code class="docutils literal"><span class="pre">False</span></code>. When <code class="docutils literal"><span class="pre">True</span></code>, errors parsing <code class="docutils literal"><span class="pre">.netrc</span></code> files cause
exceptions to be thrown.</li>
<li>Change to bundled projects import logic to make it easier to unbundle
requests downstream.</li>
<li>Changed the default User-Agent string to avoid leaking data on Linux: now
contains only the requests version.</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>The <code class="docutils literal"><span class="pre">json</span></code> parameter to <code class="docutils literal"><span class="pre">post()</span></code> and friends will now only be used if
neither <code class="docutils literal"><span class="pre">data</span></code> nor <code class="docutils literal"><span class="pre">files</span></code> are present, consistent with the
documentation.</li>
<li>We now ignore empty fields in the <code class="docutils literal"><span class="pre">NO_PROXY</span></code> environment variable.</li>
<li>Fixed problem where <code class="docutils literal"><span class="pre">httplib.BadStatusLine</span></code> would get raised if combining
<code class="docutils literal"><span class="pre">stream=True</span></code> with <code class="docutils literal"><span class="pre">contextlib.closing</span></code>.</li>
<li>Prevented bugs where we would attempt to return the same connection back to
the connection pool twice when sending a Chunked body.</li>
<li>Miscellaneous minor internal changes.</li>
<li>Digest Auth support is now thread safe.</li>
</ul>
<p><strong>Updates</strong></p>
<ul class="simple">
<li>Updated urllib3 to 1.12.</li>
</ul>
</div>
<div class="section" id="id5">
<h5>2.7.0 (2015-05-03)<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
<p>This is the first release that follows our new release process. For more, see
<a class="reference external" href="#">our documentation</a>.</p>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Updated urllib3 to 1.10.4, resolving several bugs involving chunked transfer
encoding and response framing.</li>
</ul>
</div>
<div class="section" id="id6">
<h5>2.6.2 (2015-04-23)<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Fix regression where compressed data that was sent as chunked data was not
properly decompressed. (#2561)</li>
</ul>
</div>
<div class="section" id="id7">
<h5>2.6.1 (2015-04-22)<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Remove VendorAlias import machinery introduced in v2.5.2.</li>
<li>Simplify the PreparedRequest.prepare API: We no longer require the user to
pass an empty list to the hooks keyword argument. (c.f. #2552)</li>
<li>Resolve redirects now receives and forwards all of the original arguments to
the adapter. (#2503)</li>
<li>Handle UnicodeDecodeErrors when trying to deal with a unicode URL that
cannot be encoded in ASCII. (#2540)</li>
<li>Populate the parsed path of the URI field when performing Digest
Authentication. (#2426)</li>
<li>Copy a PreparedRequest&#8217;s CookieJar more reliably when it is not an instance
of RequestsCookieJar. (#2527)</li>
</ul>
</div>
<div class="section" id="id8">
<h5>2.6.0 (2015-03-14)<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>CVE-2015-2296: Fix handling of cookies on redirect. Previously a cookie
without a host value set would use the hostname for the redirected URL
exposing requests users to session fixation attacks and potentially cookie
stealing. This was disclosed privately by Matthew Daley of
<a class="reference external" href="#">BugFuzz</a>. This affects all versions of requests from
v2.1.0 to v2.5.3 (inclusive on both ends).</li>
<li>Fix error when requests is an <code class="docutils literal"><span class="pre">install_requires</span></code> dependency and <code class="docutils literal"><span class="pre">python</span>
<span class="pre">setup.py</span> <span class="pre">test</span></code> is run. (#2462)</li>
<li>Fix error when urllib3 is unbundled and requests continues to use the
vendored import location.</li>
<li>Include fixes to <code class="docutils literal"><span class="pre">urllib3</span></code>&#8216;s header handling.</li>
<li>Requests&#8217; handling of unvendored dependencies is now more restrictive.</li>
</ul>
<p><strong>Features and Improvements</strong></p>
<ul class="simple">
<li>Support bytearrays when passed as parameters in the <code class="docutils literal"><span class="pre">files</span></code> argument.
(#2468)</li>
<li>Avoid data duplication when creating a request with <code class="docutils literal"><span class="pre">str</span></code>, <code class="docutils literal"><span class="pre">bytes</span></code>, or
<code class="docutils literal"><span class="pre">bytearray</span></code> input to the <code class="docutils literal"><span class="pre">files</span></code> argument.</li>
</ul>
</div>
<div class="section" id="id9">
<h5>2.5.3 (2015-02-24)<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Revert changes to our vendored certificate bundle. For more context see
(#2455, #2456, and <a class="reference external" href="#">http://bugs.python.org/issue23476</a>)</li>
</ul>
</div>
<div class="section" id="id10">
<h5>2.5.2 (2015-02-23)<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h5>
<p><strong>Features and Improvements</strong></p>
<ul class="simple">
<li>Add sha256 fingerprint support. (<a class="reference external" href="#">shazow/urllib3#540</a>)</li>
<li>Improve the performance of headers. (<a class="reference external" href="#">shazow/urllib3#544</a>)</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Copy pip&#8217;s import machinery. When downstream redistributors remove
requests.packages.urllib3 the import machinery will continue to let those
same symbols work. Example usage in requests&#8217; documentation and 3rd-party
libraries relying on the vendored copies of urllib3 will work without having
to fallback to the system urllib3.</li>
<li>Attempt to quote parts of the URL on redirect if unquoting and then quoting
fails. (#2356)</li>
<li>Fix filename type check for multipart form-data uploads. (#2411)</li>
<li>Properly handle the case where a server issuing digest authentication
challenges provides both auth and auth-int qop-values. (#2408)</li>
<li>Fix a socket leak. (<a class="reference external" href="#">shazow/urllib3#549</a>)</li>
<li>Fix multiple <code class="docutils literal"><span class="pre">Set-Cookie</span></code> headers properly. (<a class="reference external" href="#">shazow/urllib3#534</a>)</li>
<li>Disable the built-in hostname verification. (<a class="reference external" href="#">shazow/urllib3#526</a>)</li>
<li>Fix the behaviour of decoding an exhausted stream. (<a class="reference external" href="#">shazow/urllib3#535</a>)</li>
</ul>
<p><strong>Security</strong></p>
<ul class="simple">
<li>Pulled in an updated <code class="docutils literal"><span class="pre">cacert.pem</span></code>.</li>
<li>Drop RC4 from the default cipher list. (<a class="reference external" href="#">shazow/urllib3#551</a>)</li>
</ul>
</div>
<div class="section" id="id11">
<h5>2.5.1 (2014-12-23)<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h5>
<p><strong>Behavioural Changes</strong></p>
<ul class="simple">
<li>Only catch HTTPErrors in raise_for_status (#2382)</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Handle LocationParseError from urllib3 (#2344)</li>
<li>Handle file-like object filenames that are not strings (#2379)</li>
<li>Unbreak HTTPDigestAuth handler. Allow new nonces to be negotiated (#2389)</li>
</ul>
</div>
<div class="section" id="id12">
<h5>2.5.0 (2014-12-01)<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h5>
<p><strong>Improvements</strong></p>
<ul class="simple">
<li>Allow usage of urllib3&#8217;s Retry object with HTTPAdapters (#2216)</li>
<li>The <code class="docutils literal"><span class="pre">iter_lines</span></code> method on a response now accepts a delimiter with which
to split the content (#2295)</li>
</ul>
<p><strong>Behavioural Changes</strong></p>
<ul class="simple">
<li>Add deprecation warnings to functions in requests.utils that will be removed
in 3.0 (#2309)</li>
<li>Sessions used by the functional API are always closed (#2326)</li>
<li>Restrict requests to HTTP/1.1 and HTTP/1.0 (stop accepting HTTP/0.9) (#2323)</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Only parse the URL once (#2353)</li>
<li>Allow Content-Length header to always be overridden (#2332)</li>
<li>Properly handle files in HTTPDigestAuth (#2333)</li>
<li>Cap redirect_cache size to prevent memory abuse (#2299)</li>
<li>Fix HTTPDigestAuth handling of redirects after authenticating successfully
(#2253)</li>
<li>Fix crash with custom method parameter to Session.request (#2317)</li>
<li>Fix how Link headers are parsed using the regular expression library (#2271)</li>
</ul>
<p><strong>Documentation</strong></p>
<ul class="simple">
<li>Add more references for interlinking (#2348)</li>
<li>Update CSS for theme (#2290)</li>
<li>Update width of buttons and sidebar (#2289)</li>
<li>Replace references of Gittip with Gratipay (#2282)</li>
<li>Add link to changelog in sidebar (#2273)</li>
</ul>
</div>
<div class="section" id="id13">
<h5>2.4.3 (2014-10-06)<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Unicode URL improvements for Python 2.</li>
<li>Re-order JSON param for backwards compat.</li>
<li>Automatically defrag authentication schemes from host/pass URIs. (<a class="reference external" href="#">#2249</a>)</li>
</ul>
</div>
<div class="section" id="id15">
<h5>2.4.2 (2014-10-05)<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h5>
<p><strong>Improvements</strong></p>
<ul class="simple">
<li>FINALLY! Add json parameter for uploads! (<a class="reference external" href="#">#2258</a>)</li>
<li>Support for bytestring URLs on Python 3.x (<a class="reference external" href="#">#2238</a>)</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Avoid getting stuck in a loop (<a class="reference external" href="#">#2244</a>)</li>
<li>Multiple calls to iter* fail with unhelpful error. (<a class="reference external" href="#">#2240</a>, <a class="reference external" href="#">#2241</a>)</li>
</ul>
<p><strong>Documentation</strong></p>
<ul class="simple">
<li>Correct redirection introduction (<a class="reference external" href="#">#2245</a>)</li>
<li>Added example of how to send multiple files in one request. (<a class="reference external" href="#">#2227</a>)</li>
<li>Clarify how to pass a custom set of CAs (<a class="reference external" href="#">#2248</a>)</li>
</ul>
</div>
<div class="section" id="id24">
<h5>2.4.1 (2014-09-09)<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Now has a &#8220;security&#8221; package extras set, <code class="docutils literal"><span class="pre">$</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">requests[security]</span></code></li>
<li>Requests will now use Certifi if it is available.</li>
<li>Capture and re-raise urllib3 ProtocolError</li>
<li>Bugfix for responses that attempt to redirect to themselves forever (wtf?).</li>
</ul>
</div>
<div class="section" id="id25">
<h5>2.4.0 (2014-08-29)<a class="headerlink" href="#id25" title="Permalink to this headline">¶</a></h5>
<p><strong>Behavioral Changes</strong></p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">Connection:</span> <span class="pre">keep-alive</span></code> header is now sent automatically.</li>
</ul>
<p><strong>Improvements</strong></p>
<ul class="simple">
<li>Support for connect timeouts! Timeout now accepts a tuple (connect, read) which is used to set individual connect and read timeouts.</li>
<li>Allow copying of PreparedRequests without headers/cookies.</li>
<li>Updated bundled urllib3 version.</li>
<li>Refactored settings loading from environment &#8211; new <cite>Session.merge_environment_settings</cite>.</li>
<li>Handle socket errors in iter_content.</li>
</ul>
</div>
<div class="section" id="id26">
<h5>2.3.0 (2014-05-16)<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h5>
<p><strong>API Changes</strong></p>
<ul class="simple">
<li>New <code class="docutils literal"><span class="pre">Response</span></code> property <code class="docutils literal"><span class="pre">is_redirect</span></code>, which is true when the
library could have processed this response as a redirection (whether
or not it actually did).</li>
<li>The <code class="docutils literal"><span class="pre">timeout</span></code> parameter now affects requests with both <code class="docutils literal"><span class="pre">stream=True</span></code> and
<code class="docutils literal"><span class="pre">stream=False</span></code> equally.</li>
<li>The change in v2.0.0 to mandate explicit proxy schemes has been reverted.
Proxy schemes now default to <code class="docutils literal"><span class="pre">http://</span></code>.</li>
<li>The <code class="docutils literal"><span class="pre">CaseInsensitiveDict</span></code> used for HTTP headers now behaves like a normal
dictionary when references as string or viewed in the interpreter.</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>No longer expose Authorization or Proxy-Authorization headers on redirect.
Fix CVE-2014-1829 and CVE-2014-1830 respectively.</li>
<li>Authorization is re-evaluated each redirect.</li>
<li>On redirect, pass url as native strings.</li>
<li>Fall-back to autodetected encoding for JSON when Unicode detection fails.</li>
<li>Headers set to <code class="docutils literal"><span class="pre">None</span></code> on the <code class="docutils literal"><span class="pre">Session</span></code> are now correctly not sent.</li>
<li>Correctly honor <code class="docutils literal"><span class="pre">decode_unicode</span></code> even if it wasn&#8217;t used earlier in the same
response.</li>
<li>Stop advertising <code class="docutils literal"><span class="pre">compress</span></code> as a supported Content-Encoding.</li>
<li>The <code class="docutils literal"><span class="pre">Response.history</span></code> parameter is now always a list.</li>
<li>Many, many <code class="docutils literal"><span class="pre">urllib3</span></code> bugfixes.</li>
</ul>
</div>
<div class="section" id="id27">
<h5>2.2.1 (2014-01-23)<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h5>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Fixes incorrect parsing of proxy credentials that contain a literal or encoded &#8216;#&#8217; character.</li>
<li>Assorted urllib3 fixes.</li>
</ul>
</div>
<div class="section" id="id28">
<h5>2.2.0 (2014-01-09)<a class="headerlink" href="#id28" title="Permalink to this headline">¶</a></h5>
<p><strong>API Changes</strong></p>
<ul class="simple">
<li>New exception: <code class="docutils literal"><span class="pre">ContentDecodingError</span></code>. Raised instead of <code class="docutils literal"><span class="pre">urllib3</span></code>
<code class="docutils literal"><span class="pre">DecodeError</span></code> exceptions.</li>
</ul>
<p><strong>Bugfixes</strong></p>
<ul class="simple">
<li>Avoid many many exceptions from the buggy implementation of <code class="docutils literal"><span class="pre">proxy_bypass</span></code> on OS X in Python 2.6.</li>
<li>Avoid crashing when attempting to get authentication credentials from ~/.netrc when running as a user without a home directory.</li>
<li>Use the correct pool size for pools of connections to proxies.</li>
<li>Fix iteration of <code class="docutils literal"><span class="pre">CookieJar</span></code> objects.</li>
<li>Ensure that cookies are persisted over redirect.</li>
<li>Switch back to using chardet, since it has merged with charade.</li>
</ul>
</div>
<div class="section" id="id29">
<h5>2.1.0 (2013-12-05)<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Updated CA Bundle, of course.</li>
<li>Cookies set on individual Requests through a <code class="docutils literal"><span class="pre">Session</span></code> (e.g. via <code class="docutils literal"><span class="pre">Session.get()</span></code>) are no longer persisted to the <code class="docutils literal"><span class="pre">Session</span></code>.</li>
<li>Clean up connections when we hit problems during chunked upload, rather than leaking them.</li>
<li>Return connections to the pool when a chunked upload is successful, rather than leaking it.</li>
<li>Match the HTTPbis recommendation for HTTP 301 redirects.</li>
<li>Prevent hanging when using streaming uploads and Digest Auth when a 401 is received.</li>
<li>Values of headers set by Requests are now always the native string type.</li>
<li>Fix previously broken SNI support.</li>
<li>Fix accessing HTTP proxies using proxy authentication.</li>
<li>Unencode HTTP Basic usernames and passwords extracted from URLs.</li>
<li>Support for IP address ranges for no_proxy environment variable</li>
<li>Parse headers correctly when users override the default <code class="docutils literal"><span class="pre">Host:</span></code> header.</li>
<li>Avoid munging the URL in case of case-sensitive servers.</li>
<li>Looser URL handling for non-HTTP/HTTPS urls.</li>
<li>Accept unicode methods in Python 2.6 and 2.7.</li>
<li>More resilient cookie handling.</li>
<li>Make <code class="docutils literal"><span class="pre">Response</span></code> objects pickleable.</li>
<li>Actually added MD5-sess to Digest Auth instead of pretending to like last time.</li>
<li>Updated internal urllib3.</li>
<li>Fixed &#64;Lukasa&#8217;s lack of taste.</li>
</ul>
</div>
<div class="section" id="id30">
<h5>2.0.1 (2013-10-24)<a class="headerlink" href="#id30" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Updated included CA Bundle with new mistrusts and automated process for the future</li>
<li>Added MD5-sess to Digest Auth</li>
<li>Accept per-file headers in multipart file POST messages.</li>
<li>Fixed: Don&#8217;t send the full URL on CONNECT messages.</li>
<li>Fixed: Correctly lowercase a redirect scheme.</li>
<li>Fixed: Cookies not persisted when set via functional API.</li>
<li>Fixed: Translate urllib3 ProxyError into a requests ProxyError derived from ConnectionError.</li>
<li>Updated internal urllib3 and chardet.</li>
</ul>
</div>
<div class="section" id="id31">
<h5>2.0.0 (2013-09-24)<a class="headerlink" href="#id31" title="Permalink to this headline">¶</a></h5>
<p><strong>API Changes:</strong></p>
<ul class="simple">
<li>Keys in the Headers dictionary are now native strings on all Python versions,
i.e. bytestrings on Python 2, unicode on Python 3.</li>
<li>Proxy URLs now <em>must</em> have an explicit scheme. A <code class="docutils literal"><span class="pre">MissingSchema</span></code> exception
will be raised if they don&#8217;t.</li>
<li>Timeouts now apply to read time if <code class="docutils literal"><span class="pre">Stream=False</span></code>.</li>
<li><code class="docutils literal"><span class="pre">RequestException</span></code> is now a subclass of <code class="docutils literal"><span class="pre">IOError</span></code>, not <code class="docutils literal"><span class="pre">RuntimeError</span></code>.</li>
<li>Added new method to <code class="docutils literal"><span class="pre">PreparedRequest</span></code> objects: <code class="docutils literal"><span class="pre">PreparedRequest.copy()</span></code>.</li>
<li>Added new method to <code class="docutils literal"><span class="pre">Session</span></code> objects: <code class="docutils literal"><span class="pre">Session.update_request()</span></code>. This
method updates a <code class="docutils literal"><span class="pre">Request</span></code> object with the data (e.g. cookies) stored on
the <code class="docutils literal"><span class="pre">Session</span></code>.</li>
<li>Added new method to <code class="docutils literal"><span class="pre">Session</span></code> objects: <code class="docutils literal"><span class="pre">Session.prepare_request()</span></code>. This
method updates and prepares a <code class="docutils literal"><span class="pre">Request</span></code> object, and returns the
corresponding <code class="docutils literal"><span class="pre">PreparedRequest</span></code> object.</li>
<li>Added new method to <code class="docutils literal"><span class="pre">HTTPAdapter</span></code> objects: <code class="docutils literal"><span class="pre">HTTPAdapter.proxy_headers()</span></code>.
This should not be called directly, but improves the subclass interface.</li>
<li><code class="docutils literal"><span class="pre">httplib.IncompleteRead</span></code> exceptions caused by incorrect chunked encoding
will now raise a Requests <code class="docutils literal"><span class="pre">ChunkedEncodingError</span></code> instead.</li>
<li>Invalid percent-escape sequences now cause a Requests <code class="docutils literal"><span class="pre">InvalidURL</span></code>
exception to be raised.</li>
<li>HTTP 208 no longer uses reason phrase <code class="docutils literal"><span class="pre">&quot;im_used&quot;</span></code>. Correctly uses
<code class="docutils literal"><span class="pre">&quot;already_reported&quot;</span></code>.</li>
<li>HTTP 226 reason added (<code class="docutils literal"><span class="pre">&quot;im_used&quot;</span></code>).</li>
</ul>
<p><strong>Bugfixes:</strong></p>
<ul class="simple">
<li>Vastly improved proxy support, including the CONNECT verb. Special thanks to
the many contributors who worked towards this improvement.</li>
<li>Cookies are now properly managed when 401 authentication responses are
received.</li>
<li>Chunked encoding fixes.</li>
<li>Support for mixed case schemes.</li>
<li>Better handling of streaming downloads.</li>
<li>Retrieve environment proxies from more locations.</li>
<li>Minor cookies fixes.</li>
<li>Improved redirect behaviour.</li>
<li>Improved streaming behaviour, particularly for compressed data.</li>
<li>Miscellaneous small Python 3 text encoding bugs.</li>
<li><code class="docutils literal"><span class="pre">.netrc</span></code> no longer overrides explicit auth.</li>
<li>Cookies set by hooks are now correctly persisted on Sessions.</li>
<li>Fix problem with cookies that specify port numbers in their host field.</li>
<li><code class="docutils literal"><span class="pre">BytesIO</span></code> can be used to perform streaming uploads.</li>
<li>More generous parsing of the <code class="docutils literal"><span class="pre">no_proxy</span></code> environment variable.</li>
<li>Non-string objects can be passed in data values alongside files.</li>
</ul>
</div>
<div class="section" id="id32">
<h5>1.2.3 (2013-05-25)<a class="headerlink" href="#id32" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Simple packaging fix</li>
</ul>
</div>
<div class="section" id="id33">
<h5>1.2.2 (2013-05-23)<a class="headerlink" href="#id33" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Simple packaging fix</li>
</ul>
</div>
<div class="section" id="id34">
<h5>1.2.1 (2013-05-20)<a class="headerlink" href="#id34" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>301 and 302 redirects now change the verb to GET for all verbs, not just
POST, improving browser compatibility.</li>
<li>Python 3.3.2 compatibility</li>
<li>Always percent-encode location headers</li>
<li>Fix connection adapter matching to be most-specific first</li>
<li>new argument to the default connection adapter for passing a block argument</li>
<li>prevent a KeyError when there&#8217;s no link headers</li>
</ul>
</div>
<div class="section" id="id35">
<h5>1.2.0 (2013-03-31)<a class="headerlink" href="#id35" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Fixed cookies on sessions and on requests</li>
<li>Significantly change how hooks are dispatched - hooks now receive all the
arguments specified by the user when making a request so hooks can make a
secondary request with the same parameters. This is especially necessary for
authentication handler authors</li>
<li>certifi support was removed</li>
<li>Fixed bug where using OAuth 1 with body <code class="docutils literal"><span class="pre">signature_type</span></code> sent no data</li>
<li>Major proxy work thanks to &#64;Lukasa including parsing of proxy authentication
from the proxy url</li>
<li>Fix DigestAuth handling too many 401s</li>
<li>Update vendored urllib3 to include SSL bug fixes</li>
<li>Allow keyword arguments to be passed to <code class="docutils literal"><span class="pre">json.loads()</span></code> via the
<code class="docutils literal"><span class="pre">Response.json()</span></code> method</li>
<li>Don&#8217;t send <code class="docutils literal"><span class="pre">Content-Length</span></code> header by default on <code class="docutils literal"><span class="pre">GET</span></code> or <code class="docutils literal"><span class="pre">HEAD</span></code>
requests</li>
<li>Add <code class="docutils literal"><span class="pre">elapsed</span></code> attribute to <code class="docutils literal"><span class="pre">Response</span></code> objects to time how long a request
took.</li>
<li>Fix <code class="docutils literal"><span class="pre">RequestsCookieJar</span></code></li>
<li>Sessions and Adapters are now picklable, i.e., can be used with the
multiprocessing library</li>
<li>Update charade to version 1.0.3</li>
</ul>
<p>The change in how hooks are dispatched will likely cause a great deal of
issues.</p>
</div>
<div class="section" id="id36">
<h5>1.1.0 (2013-01-10)<a class="headerlink" href="#id36" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>CHUNKED REQUESTS</li>
<li>Support for iterable response bodies</li>
<li>Assume servers persist redirect params</li>
<li>Allow explicit content types to be specified for file data</li>
<li>Make merge_kwargs case-insensitive when looking up keys</li>
</ul>
</div>
<div class="section" id="id37">
<h5>1.0.3 (2012-12-18)<a class="headerlink" href="#id37" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Fix file upload encoding bug</li>
<li>Fix cookie behavior</li>
</ul>
</div>
<div class="section" id="id38">
<h5>1.0.2 (2012-12-17)<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Proxy fix for HTTPAdapter.</li>
</ul>
</div>
<div class="section" id="id39">
<h5>1.0.1 (2012-12-17)<a class="headerlink" href="#id39" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Cert verification exception bug.</li>
<li>Proxy fix for HTTPAdapter.</li>
</ul>
</div>
<div class="section" id="id40">
<h5>1.0.0 (2012-12-17)<a class="headerlink" href="#id40" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Massive Refactor and Simplification</li>
<li>Switch to Apache 2.0 license</li>
<li>Swappable Connection Adapters</li>
<li>Mountable Connection Adapters</li>
<li>Mutable ProcessedRequest chain</li>
<li>/s/prefetch/stream</li>
<li>Removal of all configuration</li>
<li>Standard library logging</li>
<li>Make Response.json() callable, not property.</li>
<li>Usage of new charade project, which provides python 2 and 3 simultaneous chardet.</li>
<li>Removal of all hooks except &#8216;response&#8217;</li>
<li>Removal of all authentication helpers (OAuth, Kerberos)</li>
</ul>
<p>This is not a backwards compatible change.</p>
</div>
<div class="section" id="id41">
<h5>0.14.2 (2012-10-27)<a class="headerlink" href="#id41" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Improved mime-compatible JSON handling</li>
<li>Proxy fixes</li>
<li>Path hack fixes</li>
<li>Case-Insensitive Content-Encoding headers</li>
<li>Support for CJK parameters in form posts</li>
</ul>
</div>
<div class="section" id="id42">
<h5>0.14.1 (2012-10-01)<a class="headerlink" href="#id42" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Python 3.3 Compatibility</li>
<li>Simply default accept-encoding</li>
<li>Bugfixes</li>
</ul>
</div>
<div class="section" id="id43">
<h5>0.14.0 (2012-09-02)<a class="headerlink" href="#id43" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>No more iter_content errors if already downloaded.</li>
</ul>
</div>
<div class="section" id="id44">
<h5>0.13.9 (2012-08-25)<a class="headerlink" href="#id44" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Fix for OAuth + POSTs</li>
<li>Remove exception eating from dispatch_hook</li>
<li>General bugfixes</li>
</ul>
</div>
<div class="section" id="id45">
<h5>0.13.8 (2012-08-21)<a class="headerlink" href="#id45" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Incredible Link header support :)</li>
</ul>
</div>
<div class="section" id="id46">
<h5>0.13.7 (2012-08-19)<a class="headerlink" href="#id46" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Support for (key, value) lists everywhere.</li>
<li>Digest Authentication improvements.</li>
<li>Ensure proxy exclusions work properly.</li>
<li>Clearer UnicodeError exceptions.</li>
<li>Automatic casting of URLs to strings (fURL and such)</li>
<li>Bugfixes.</li>
</ul>
</div>
<div class="section" id="id47">
<h5>0.13.6 (2012-08-06)<a class="headerlink" href="#id47" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Long awaited fix for hanging connections!</li>
</ul>
</div>
<div class="section" id="id48">
<h5>0.13.5 (2012-07-27)<a class="headerlink" href="#id48" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Packaging fix</li>
</ul>
</div>
<div class="section" id="id49">
<h5>0.13.4 (2012-07-27)<a class="headerlink" href="#id49" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>GSSAPI/Kerberos authentication!</li>
<li>App Engine 2.7 Fixes!</li>
<li>Fix leaking connections (from urllib3 update)</li>
<li>OAuthlib path hack fix</li>
<li>OAuthlib URL parameters fix.</li>
</ul>
</div>
<div class="section" id="id50">
<h5>0.13.3 (2012-07-12)<a class="headerlink" href="#id50" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Use simplejson if available.</li>
<li>Do not hide SSLErrors behind Timeouts.</li>
<li>Fixed param handling with urls containing fragments.</li>
<li>Significantly improved information in User Agent.</li>
<li>client certificates are ignored when verify=False</li>
</ul>
</div>
<div class="section" id="id51">
<h5>0.13.2 (2012-06-28)<a class="headerlink" href="#id51" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Zero dependencies (once again)!</li>
<li>New: Response.reason</li>
<li>Sign querystring parameters in OAuth 1.0</li>
<li>Client certificates no longer ignored when verify=False</li>
<li>Add openSUSE certificate support</li>
</ul>
</div>
<div class="section" id="id52">
<h5>0.13.1 (2012-06-07)<a class="headerlink" href="#id52" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Allow passing a file or file-like object as data.</li>
<li>Allow hooks to return responses that indicate errors.</li>
<li>Fix Response.text and Response.json for body-less responses.</li>
</ul>
</div>
<div class="section" id="id53">
<h5>0.13.0 (2012-05-29)<a class="headerlink" href="#id53" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Removal of Requests.async in favor of <a class="reference external" href="#">grequests</a></li>
<li>Allow disabling of cookie persistence.</li>
<li>New implementation of safe_mode</li>
<li>cookies.get now supports default argument</li>
<li>Session cookies not saved when Session.request is called with return_response=False</li>
<li>Env: no_proxy support.</li>
<li>RequestsCookieJar improvements.</li>
<li>Various bug fixes.</li>
</ul>
</div>
<div class="section" id="id54">
<h5>0.12.1 (2012-05-08)<a class="headerlink" href="#id54" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>New <code class="docutils literal"><span class="pre">Response.json</span></code> property.</li>
<li>Ability to add string file uploads.</li>
<li>Fix out-of-range issue with iter_lines.</li>
<li>Fix iter_content default size.</li>
<li>Fix POST redirects containing files.</li>
</ul>
</div>
<div class="section" id="id55">
<h5>0.12.0 (2012-05-02)<a class="headerlink" href="#id55" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>EXPERIMENTAL OAUTH SUPPORT!</li>
<li>Proper CookieJar-backed cookies interface with awesome dict-like interface.</li>
<li>Speed fix for non-iterated content chunks.</li>
<li>Move <code class="docutils literal"><span class="pre">pre_request</span></code> to a more usable place.</li>
<li>New <code class="docutils literal"><span class="pre">pre_send</span></code> hook.</li>
<li>Lazily encode data, params, files.</li>
<li>Load system Certificate Bundle if <code class="docutils literal"><span class="pre">certify</span></code> isn&#8217;t available.</li>
<li>Cleanups, fixes.</li>
</ul>
</div>
<div class="section" id="id56">
<h5>0.11.2 (2012-04-22)<a class="headerlink" href="#id56" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Attempt to use the OS&#8217;s certificate bundle if <code class="docutils literal"><span class="pre">certifi</span></code> isn&#8217;t available.</li>
<li>Infinite digest auth redirect fix.</li>
<li>Multi-part file upload improvements.</li>
<li>Fix decoding of invalid %encodings in URLs.</li>
<li>If there is no content in a response don&#8217;t throw an error the second time that content is attempted to be read.</li>
<li>Upload data on redirects.</li>
</ul>
</div>
<div class="section" id="id57">
<h5>0.11.1 (2012-03-30)<a class="headerlink" href="#id57" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>POST redirects now break RFC to do what browsers do: Follow up with a GET.</li>
<li>New <code class="docutils literal"><span class="pre">strict_mode</span></code> configuration to disable new redirect behavior.</li>
</ul>
</div>
<div class="section" id="id58">
<h5>0.11.0 (2012-03-14)<a class="headerlink" href="#id58" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Private SSL Certificate support</li>
<li>Remove select.poll from Gevent monkeypatching</li>
<li>Remove redundant generator for chunked transfer encoding</li>
<li>Fix: Response.ok raises Timeout Exception in safe_mode</li>
</ul>
</div>
<div class="section" id="id59">
<h5>0.10.8 (2012-03-09)<a class="headerlink" href="#id59" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Generate chunked ValueError fix</li>
<li>Proxy configuration by environment variables</li>
<li>Simplification of iter_lines.</li>
<li>New <cite>trust_env</cite> configuration for disabling system/environment hints.</li>
<li>Suppress cookie errors.</li>
</ul>
</div>
<div class="section" id="id60">
<h5>0.10.7 (2012-03-07)<a class="headerlink" href="#id60" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li><cite>encode_uri</cite> = False</li>
</ul>
</div>
<div class="section" id="id61">
<h5>0.10.6 (2012-02-25)<a class="headerlink" href="#id61" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Allow &#8216;=&#8217; in cookies.</li>
</ul>
</div>
<div class="section" id="id62">
<h5>0.10.5 (2012-02-25)<a class="headerlink" href="#id62" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Response body with 0 content-length fix.</li>
<li>New async.imap.</li>
<li>Don&#8217;t fail on netrc.</li>
</ul>
</div>
<div class="section" id="id63">
<h5>0.10.4 (2012-02-20)<a class="headerlink" href="#id63" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Honor netrc.</li>
</ul>
</div>
<div class="section" id="id64">
<h5>0.10.3 (2012-02-20)<a class="headerlink" href="#id64" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>HEAD requests don&#8217;t follow redirects anymore.</li>
<li>raise_for_status() doesn&#8217;t raise for 3xx anymore.</li>
<li>Make Session objects picklable.</li>
<li>ValueError for invalid schema URLs.</li>
</ul>
</div>
<div class="section" id="id65">
<h5>0.10.2 (2012-01-15)<a class="headerlink" href="#id65" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Vastly improved URL quoting.</li>
<li>Additional allowed cookie key values.</li>
<li>Attempted fix for &#8220;Too many open files&#8221; Error</li>
<li>Replace unicode errors on first pass, no need for second pass.</li>
<li>Append &#8216;/&#8217; to bare-domain urls before query insertion.</li>
<li>Exceptions now inherit from RuntimeError.</li>
<li>Binary uploads + auth fix.</li>
<li>Bugfixes.</li>
</ul>
</div>
<div class="section" id="id66">
<h5>0.10.1 (2012-01-23)<a class="headerlink" href="#id66" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>PYTHON 3 SUPPORT!</li>
<li>Dropped 2.5 Support. (<em>Backwards Incompatible</em>)</li>
</ul>
</div>
<div class="section" id="id67">
<h5>0.10.0 (2012-01-21)<a class="headerlink" href="#id67" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">Response.content</span></code> is now bytes-only. (<em>Backwards Incompatible</em>)</li>
<li>New <code class="docutils literal"><span class="pre">Response.text</span></code> is unicode-only.</li>
<li>If no <code class="docutils literal"><span class="pre">Response.encoding</span></code> is specified and <code class="docutils literal"><span class="pre">chardet</span></code> is available, <code class="docutils literal"><span class="pre">Response.text</span></code> will guess an encoding.</li>
<li>Default to ISO-8859-1 (Western) encoding for &#8220;text&#8221; subtypes.</li>
<li>Removal of <cite>decode_unicode</cite>. (<em>Backwards Incompatible</em>)</li>
<li>New multiple-hooks system.</li>
<li>New <code class="docutils literal"><span class="pre">Response.register_hook</span></code> for registering hooks within the pipeline.</li>
<li><code class="docutils literal"><span class="pre">Response.url</span></code> is now Unicode.</li>
</ul>
</div>
<div class="section" id="id68">
<h5>0.9.3 (2012-01-18)<a class="headerlink" href="#id68" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>SSL verify=False bugfix (apparent on windows machines).</li>
</ul>
</div>
<div class="section" id="id69">
<h5>0.9.2 (2012-01-18)<a class="headerlink" href="#id69" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Asynchronous async.send method.</li>
<li>Support for proper chunk streams with boundaries.</li>
<li>session argument for Session classes.</li>
<li>Print entire hook tracebacks, not just exception instance.</li>
<li>Fix response.iter_lines from pending next line.</li>
<li>Fix but in HTTP-digest auth w/ URI having query strings.</li>
<li>Fix in Event Hooks section.</li>
<li>Urllib3 update.</li>
</ul>
</div>
<div class="section" id="id70">
<h5>0.9.1 (2012-01-06)<a class="headerlink" href="#id70" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>danger_mode for automatic Response.raise_for_status()</li>
<li>Response.iter_lines refactor</li>
</ul>
</div>
<div class="section" id="id71">
<h5>0.9.0 (2011-12-28)<a class="headerlink" href="#id71" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>verify ssl is default.</li>
</ul>
</div>
<div class="section" id="id72">
<h5>0.8.9 (2011-12-28)<a class="headerlink" href="#id72" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Packaging fix.</li>
</ul>
</div>
<div class="section" id="id73">
<h5>0.8.8 (2011-12-28)<a class="headerlink" href="#id73" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>SSL CERT VERIFICATION!</li>
<li>Release of Cerifi: Mozilla&#8217;s cert list.</li>
<li>New &#8216;verify&#8217; argument for SSL requests.</li>
<li>Urllib3 update.</li>
</ul>
</div>
<div class="section" id="id74">
<h5>0.8.7 (2011-12-24)<a class="headerlink" href="#id74" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>iter_lines last-line truncation fix</li>
<li>Force safe_mode for async requests</li>
<li>Handle safe_mode exceptions more consistently</li>
<li>Fix iteration on null responses in safe_mode</li>
</ul>
</div>
<div class="section" id="id75">
<h5>0.8.6 (2011-12-18)<a class="headerlink" href="#id75" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Socket timeout fixes.</li>
<li>Proxy Authorization support.</li>
</ul>
</div>
<div class="section" id="id76">
<h5>0.8.5 (2011-12-14)<a class="headerlink" href="#id76" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Response.iter_lines!</li>
</ul>
</div>
<div class="section" id="id77">
<h5>0.8.4 (2011-12-11)<a class="headerlink" href="#id77" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Prefetch bugfix.</li>
<li>Added license to installed version.</li>
</ul>
</div>
<div class="section" id="id78">
<h5>0.8.3 (2011-11-27)<a class="headerlink" href="#id78" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Converted auth system to use simpler callable objects.</li>
<li>New session parameter to API methods.</li>
<li>Display full URL while logging.</li>
</ul>
</div>
<div class="section" id="id79">
<h5>0.8.2 (2011-11-19)<a class="headerlink" href="#id79" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>New Unicode decoding system, based on over-ridable <cite>Response.encoding</cite>.</li>
<li>Proper URL slash-quote handling.</li>
<li>Cookies with <code class="docutils literal"><span class="pre">[</span></code>, <code class="docutils literal"><span class="pre">]</span></code>, and <code class="docutils literal"><span class="pre">_</span></code> allowed.</li>
</ul>
</div>
<div class="section" id="id80">
<h5>0.8.1 (2011-11-15)<a class="headerlink" href="#id80" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>URL Request path fix</li>
<li>Proxy fix.</li>
<li>Timeouts fix.</li>
</ul>
</div>
<div class="section" id="id81">
<h5>0.8.0 (2011-11-13)<a class="headerlink" href="#id81" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Keep-alive support!</li>
<li>Complete removal of Urllib2</li>
<li>Complete removal of Poster</li>
<li>Complete removal of CookieJars</li>
<li>New ConnectionError raising</li>
<li>Safe_mode for error catching</li>
<li>prefetch parameter for request methods</li>
<li>OPTION method</li>
<li>Async pool size throttling</li>
<li>File uploads send real names</li>
<li>Vendored in urllib3</li>
</ul>
</div>
<div class="section" id="id82">
<h5>0.7.6 (2011-11-07)<a class="headerlink" href="#id82" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Digest authentication bugfix (attach query data to path)</li>
</ul>
</div>
<div class="section" id="id83">
<h5>0.7.5 (2011-11-04)<a class="headerlink" href="#id83" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Response.content = None if there was an invalid response.</li>
<li>Redirection auth handling.</li>
</ul>
</div>
<div class="section" id="id84">
<h5>0.7.4 (2011-10-26)<a class="headerlink" href="#id84" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Session Hooks fix.</li>
</ul>
</div>
<div class="section" id="id85">
<h5>0.7.3 (2011-10-23)<a class="headerlink" href="#id85" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Digest Auth fix.</li>
</ul>
</div>
<div class="section" id="id86">
<h5>0.7.2 (2011-10-23)<a class="headerlink" href="#id86" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>PATCH Fix.</li>
</ul>
</div>
<div class="section" id="id87">
<h5>0.7.1 (2011-10-23)<a class="headerlink" href="#id87" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Move away from urllib2 authentication handling.</li>
<li>Fully Remove AuthManager, AuthObject, &amp;c.</li>
<li>New tuple-based auth system with handler callbacks.</li>
</ul>
</div>
<div class="section" id="id88">
<h5>0.7.0 (2011-10-22)<a class="headerlink" href="#id88" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Sessions are now the primary interface.</li>
<li>Deprecated InvalidMethodException.</li>
<li>PATCH fix.</li>
<li>New config system (no more global settings).</li>
</ul>
</div>
<div class="section" id="id89">
<h5>0.6.6 (2011-10-19)<a class="headerlink" href="#id89" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Session parameter bugfix (params merging).</li>
</ul>
</div>
<div class="section" id="id90">
<h5>0.6.5 (2011-10-18)<a class="headerlink" href="#id90" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Offline (fast) test suite.</li>
<li>Session dictionary argument merging.</li>
</ul>
</div>
<div class="section" id="id91">
<h5>0.6.4 (2011-10-13)<a class="headerlink" href="#id91" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Automatic decoding of unicode, based on HTTP Headers.</li>
<li>New <code class="docutils literal"><span class="pre">decode_unicode</span></code> setting.</li>
<li>Removal of <code class="docutils literal"><span class="pre">r.read/close</span></code> methods.</li>
<li>New <code class="docutils literal"><span class="pre">r.faw</span></code> interface for advanced response usage.*</li>
<li>Automatic expansion of parameterized headers.</li>
</ul>
</div>
<div class="section" id="id92">
<h5>0.6.3 (2011-10-13)<a class="headerlink" href="#id92" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Beautiful <code class="docutils literal"><span class="pre">requests.async</span></code> module, for making async requests w/ gevent.</li>
</ul>
</div>
<div class="section" id="id93">
<h5>0.6.2 (2011-10-09)<a class="headerlink" href="#id93" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>GET/HEAD obeys allow_redirects=False.</li>
</ul>
</div>
<div class="section" id="id94">
<h5>0.6.1 (2011-08-20)<a class="headerlink" href="#id94" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Enhanced status codes experience <code class="docutils literal"><span class="pre">\o/</span></code></li>
<li>Set a maximum number of redirects (<code class="docutils literal"><span class="pre">settings.max_redirects</span></code>)</li>
<li>Full Unicode URL support</li>
<li>Support for protocol-less redirects.</li>
<li>Allow for arbitrary request types.</li>
<li>Bugfixes</li>
</ul>
</div>
<div class="section" id="id95">
<h5>0.6.0 (2011-08-17)<a class="headerlink" href="#id95" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>New callback hook system</li>
<li>New persistent sessions object and context manager</li>
<li>Transparent Dict-cookie handling</li>
<li>Status code reference object</li>
<li>Removed Response.cached</li>
<li>Added Response.request</li>
<li>All args are kwargs</li>
<li>Relative redirect support</li>
<li>HTTPError handling improvements</li>
<li>Improved https testing</li>
<li>Bugfixes</li>
</ul>
</div>
<div class="section" id="id96">
<h5>0.5.1 (2011-07-23)<a class="headerlink" href="#id96" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>International Domain Name Support!</li>
<li>Access headers without fetching entire body (<code class="docutils literal"><span class="pre">read()</span></code>)</li>
<li>Use lists as dicts for parameters</li>
<li>Add Forced Basic Authentication</li>
<li>Forced Basic is default authentication type</li>
<li><code class="docutils literal"><span class="pre">python-requests.org</span></code> default User-Agent header</li>
<li>CaseInsensitiveDict lower-case caching</li>
<li>Response.history bugfix</li>
</ul>
</div>
<div class="section" id="id97">
<h5>0.5.0 (2011-06-21)<a class="headerlink" href="#id97" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>PATCH Support</li>
<li>Support for Proxies</li>
<li>HTTPBin Test Suite</li>
<li>Redirect Fixes</li>
<li>settings.verbose stream writing</li>
<li>Querystrings for all methods</li>
<li>URLErrors (Connection Refused, Timeout, Invalid URLs) are treated as explicitly raised
<code class="docutils literal"><span class="pre">r.requests.get('hwe://blah');</span> <span class="pre">r.raise_for_status()</span></code></li>
</ul>
</div>
<div class="section" id="id98">
<h5>0.4.1 (2011-05-22)<a class="headerlink" href="#id98" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Improved Redirection Handling</li>
<li>New &#8216;allow_redirects&#8217; param for following non-GET/HEAD Redirects</li>
<li>Settings module refactoring</li>
</ul>
</div>
<div class="section" id="id99">
<h5>0.4.0 (2011-05-15)<a class="headerlink" href="#id99" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Response.history: list of redirected responses</li>
<li>Case-Insensitive Header Dictionaries!</li>
<li>Unicode URLs</li>
</ul>
</div>
<div class="section" id="id100">
<h5>0.3.4 (2011-05-14)<a class="headerlink" href="#id100" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Urllib2 HTTPAuthentication Recursion fix (Basic/Digest)</li>
<li>Internal Refactor</li>
<li>Bytes data upload Bugfix</li>
</ul>
</div>
<div class="section" id="id101">
<h5>0.3.3 (2011-05-12)<a class="headerlink" href="#id101" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Request timeouts</li>
<li>Unicode url-encoded data</li>
<li>Settings context manager and module</li>
</ul>
</div>
<div class="section" id="id102">
<h5>0.3.2 (2011-04-15)<a class="headerlink" href="#id102" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Automatic Decompression of GZip Encoded Content</li>
<li>AutoAuth Support for Tupled HTTP Auth</li>
</ul>
</div>
<div class="section" id="id103">
<h5>0.3.1 (2011-04-01)<a class="headerlink" href="#id103" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Cookie Changes</li>
<li>Response.read()</li>
<li>Poster fix</li>
</ul>
</div>
<div class="section" id="id104">
<h5>0.3.0 (2011-02-25)<a class="headerlink" href="#id104" title="Permalink to this headline">¶</a></h5>
<ul>
<li><p class="first">Automatic Authentication API Change</p>
</li>
<li><p class="first">Smarter Query URL Parameterization</p>
</li>
<li><p class="first">Allow file uploads and POST data together</p>
</li>
<li><dl class="first docutils">
<dt>New Authentication Manager System</dt>
<dd><ul class="first last simple">
<li>Simpler Basic HTTP System</li>
<li>Supports all build-in urllib2 Auths</li>
<li>Allows for custom Auth Handlers</li>
</ul>
</dd>
</dl>
</li>
</ul>
</div>
<div class="section" id="id105">
<h5>0.2.4 (2011-02-19)<a class="headerlink" href="#id105" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Python 2.5 Support</li>
<li>PyPy-c v1.4 Support</li>
<li>Auto-Authentication tests</li>
<li>Improved Request object constructor</li>
</ul>
</div>
<div class="section" id="id106">
<h5>0.2.3 (2011-02-15)<a class="headerlink" href="#id106" title="Permalink to this headline">¶</a></h5>
<ul>
<li><dl class="first docutils">
<dt>New HTTPHandling Methods</dt>
<dd><ul class="first last simple">
<li>Response.__nonzero__ (false if bad HTTP Status)</li>
<li>Response.ok (True if expected HTTP Status)</li>
<li>Response.error (Logged HTTPError if bad HTTP Status)</li>
<li>Response.raise_for_status() (Raises stored HTTPError)</li>
</ul>
</dd>
</dl>
</li>
</ul>
</div>
<div class="section" id="id107">
<h5>0.2.2 (2011-02-14)<a class="headerlink" href="#id107" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Still handles request in the event of an HTTPError. (Issue #2)</li>
<li>Eventlet and Gevent Monkeypatch support.</li>
<li>Cookie Support (Issue #1)</li>
</ul>
</div>
<div class="section" id="id108">
<h5>0.2.1 (2011-02-14)<a class="headerlink" href="#id108" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Added file attribute to POST and PUT requests for multipart-encode file uploads.</li>
<li>Added Request.url attribute for context and redirects</li>
</ul>
</div>
<div class="section" id="id109">
<h5>0.2.0 (2011-02-14)<a class="headerlink" href="#id109" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Birth!</li>
</ul>
</div>
<div class="section" id="id110">
<h5>0.0.1 (2011-02-13)<a class="headerlink" href="#id110" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Frustration</li>
<li>Conception</li>
</ul>
</div>
</div>
</div>
<span id="document-community/release-process"></span><div class="section" id="release-process-and-rules">
<h3>Release Process and Rules<a class="headerlink" href="#release-process-and-rules" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified">New in version v2.6.2.</span></p>
</div>
<p>Starting with the version to be released after <code class="docutils literal"><span class="pre">v2.6.2</span></code>, the following rules
will govern and describe how the Requests core team produces a new release.</p>
<div class="section" id="major-releases">
<h4>Major Releases<a class="headerlink" href="#major-releases" title="Permalink to this headline">¶</a></h4>
<p>A major release will include breaking changes. When it is versioned, it will
be versioned as <code class="docutils literal"><span class="pre">vX.0.0</span></code>. For example, if the previous release was
<code class="docutils literal"><span class="pre">v10.2.7</span></code> the next version will be <code class="docutils literal"><span class="pre">v11.0.0</span></code>.</p>
<p>Breaking changes are changes that break backwards compatibility with prior
versions. If the project were to change the <code class="docutils literal"><span class="pre">text</span></code> attribute on a
<code class="docutils literal"><span class="pre">Response</span></code> object to a method, that would only happen in a Major release.</p>
<p>Major releases may also include miscellaneous bug fixes and upgrades to
vendored packages. The core developers of Requests are committed to providing
a good user experience. This means we&#8217;re also committed to preserving
backwards compatibility as much as possible. Major releases will be infrequent
and will need strong justifications before they are considered.</p>
</div>
<div class="section" id="minor-releases">
<h4>Minor Releases<a class="headerlink" href="#minor-releases" title="Permalink to this headline">¶</a></h4>
<p>A minor release will not include breaking changes but may include
miscellaneous bug fixes and upgrades to vendored packages. If the previous
version of Requests released was <code class="docutils literal"><span class="pre">v10.2.7</span></code> a minor release would be
versioned as <code class="docutils literal"><span class="pre">v10.3.0</span></code>.</p>
<p>Minor releases will be backwards compatible with releases that have the same
major version number. In other words, all versions that would start with
<code class="docutils literal"><span class="pre">v10.</span></code> should be compatible with each other.</p>
</div>
<div class="section" id="hotfix-releases">
<h4>Hotfix Releases<a class="headerlink" href="#hotfix-releases" title="Permalink to this headline">¶</a></h4>
<p>A hotfix release will only include bug fixes that were missed when the project
released the previous version. If the previous version of Requests released
<code class="docutils literal"><span class="pre">v10.2.7</span></code> the hotfix release would be versioned as <code class="docutils literal"><span class="pre">v10.2.8</span></code>.</p>
<p>Hotfixes will <strong>not</strong> include upgrades to vendored dependences after
<code class="docutils literal"><span class="pre">v2.6.2</span></code></p>
</div>
<div class="section" id="reasoning">
<h4>Reasoning<a class="headerlink" href="#reasoning" title="Permalink to this headline">¶</a></h4>
<p>In the 2.5 and 2.6 release series, the Requests core team upgraded vendored
dependencies and caused a great deal of headaches for both users and the core
team. To reduce this pain, we&#8217;re forming a concrete set of procedures so
expectations will be properly set.</p>
</div>
</div>
</div>
</div>
<div class="section" id="api-documentation">
<h2>API Documentation<a class="headerlink" href="#api-documentation" title="Permalink to this headline">¶</a></h2>
<p>If you are looking for information on a specific function, class or method,
this part of the documentation is for you.</p>
<div class="toctree-wrapper compound">
<span id="document-api"></span><div class="section" id="module-requests">
<span id="developer-interface"></span><span id="api"></span><h3>Developer Interface<a class="headerlink" href="#module-requests" title="Permalink to this headline">¶</a></h3>
<p>This part of the documentation covers all the interfaces of Requests. For
parts where Requests depends on external libraries, we document the most
important right here and provide links to the canonical documentation.</p>
<div class="section" id="main-interface">
<h4>Main Interface<a class="headerlink" href="#main-interface" title="Permalink to this headline">¶</a></h4>
<p>All of Requests&#8217; functionality can be accessed by these 7 methods.
They all return an instance of the <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<dl class="function">
<dt id="requests.request">
<code class="descclassname">requests.</code><code class="descname">request</code><span class="sig-paren">(</span><em>method</em>, <em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.request" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs and sends a <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>method</strong> &#8211; method for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>params</strong> &#8211; (optional) Dictionary or bytes to be sent in the query string for the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json data to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>headers</strong> &#8211; (optional) Dictionary of HTTP Headers to send with the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>cookies</strong> &#8211; (optional) Dict or CookieJar object to send with the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>files</strong> &#8211; (optional) Dictionary of <code class="docutils literal"><span class="pre">'name':</span> <span class="pre">file-like-objects</span></code> (or <code class="docutils literal"><span class="pre">{'name':</span> <span class="pre">('filename',</span> <span class="pre">fileobj)}</span></code>) for multipart encoding upload.</li>
<li><strong>auth</strong> &#8211; (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.</li>
<li><strong>timeout</strong> (<em>float or tuple</em>) &#8211; (optional) How long to wait for the server to send data
before giving up, as a float, or a <a class="reference internal" href="index.html#timeouts"><span>(connect timeout, read
timeout)</span></a> tuple.</li>
<li><strong>allow_redirects</strong> (<em>bool</em>) &#8211; (optional) Boolean. Set to True if POST/PUT/DELETE redirect following is allowed.</li>
<li><strong>proxies</strong> &#8211; (optional) Dictionary mapping protocol to the URL of the proxy.</li>
<li><strong>verify</strong> &#8211; (optional) whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to <code class="docutils literal"><span class="pre">True</span></code>.</li>
<li><strong>stream</strong> &#8211; (optional) if <code class="docutils literal"><span class="pre">False</span></code>, the response content will be immediately downloaded.</li>
<li><strong>cert</strong> &#8211; (optional) if String, path to ssl client cert file (.pem). If Tuple, (&#8216;cert&#8217;, &#8216;key&#8217;) pair.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="requests.head">
<code class="descclassname">requests.</code><code class="descname">head</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.head" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a HEAD request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.get">
<code class="descclassname">requests.</code><code class="descname">get</code><span class="sig-paren">(</span><em>url</em>, <em>params=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a GET request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>params</strong> &#8211; (optional) Dictionary or bytes to be sent in the query string for the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.post">
<code class="descclassname">requests.</code><code class="descname">post</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>json=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.post" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a POST request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json data to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.put">
<code class="descclassname">requests.</code><code class="descname">put</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.put" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a PUT request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.patch">
<code class="descclassname">requests.</code><code class="descname">patch</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.patch" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a PATCH request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.delete">
<code class="descclassname">requests.</code><code class="descname">delete</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a DELETE request.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last"><a class="reference internal" href="index.html#requests.Response" title="requests.Response">requests.Response</a></p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<div class="section" id="lower-level-classes">
<h5>Lower-Level Classes<a class="headerlink" href="#lower-level-classes" title="Permalink to this headline">¶</a></h5>
<dl class="class">
<dt id="requests.Request">
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Request</code><span class="sig-paren">(</span><em>method=None</em>, <em>url=None</em>, <em>headers=None</em>, <em>files=None</em>, <em>data=None</em>, <em>params=None</em>, <em>auth=None</em>, <em>cookies=None</em>, <em>hooks=None</em>, <em>json=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Request" title="Permalink to this definition">¶</a></dt>
<dd><p>A user-created <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</p>
<p>Used to prepare a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a>, which is sent to the server.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>method</strong> &#8211; HTTP method to use.</li>
<li><strong>url</strong> &#8211; URL to send.</li>
<li><strong>headers</strong> &#8211; dictionary of headers to send.</li>
<li><strong>files</strong> &#8211; dictionary of {filename: fileobject} files to multipart upload.</li>
<li><strong>data</strong> &#8211; the body to attach to the request. If a dictionary is provided, form-encoding will take place.</li>
<li><strong>json</strong> &#8211; json for the body to attach to the request (if files or data is not specified).</li>
<li><strong>params</strong> &#8211; dictionary of URL parameters to append to the URL.</li>
<li><strong>auth</strong> &#8211; Auth handler or (user, pass) tuple.</li>
<li><strong>cookies</strong> &#8211; dictionary or CookieJar of cookies to attach to this request.</li>
<li><strong>hooks</strong> &#8211; dictionary of callback hooks, for internal usage.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span><span class="o">.</span><span class="n">prepare</span><span class="p">()</span>
<span class="go">&lt;PreparedRequest [GET]&gt;</span>
</pre></div>
</div>
<dl class="method">
<dt id="requests.Request.deregister_hook">
<code class="descname">deregister_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Request.deregister_hook" title="Permalink to this definition">¶</a></dt>
<dd><p>Deregister a previously registered hook.
Returns True if the hook existed, False if not.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Request.prepare">
<code class="descname">prepare</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.Request.prepare" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> for transmission and returns it.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Request.register_hook">
<code class="descname">register_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Request.register_hook" title="Permalink to this definition">¶</a></dt>
<dd><p>Properly register a hook.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="requests.Response">
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Response</code><a class="headerlink" href="#requests.Response" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object, which contains a
server&#8217;s response to an HTTP request.</p>
<dl class="attribute">
<dt id="requests.Response.apparent_encoding">
<code class="descname">apparent_encoding</code><a class="headerlink" href="#requests.Response.apparent_encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>The apparent encoding, provided by the chardet library</p>
</dd></dl>

<dl class="method">
<dt id="requests.Response.close">
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.Response.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Releases the connection back to the pool. Once this method has been
called the underlying <code class="docutils literal"><span class="pre">raw</span></code> object must not be accessed again.</p>
<p><em>Note: Should not normally need to be called explicitly.</em></p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.content">
<code class="descname">content</code><a class="headerlink" href="#requests.Response.content" title="Permalink to this definition">¶</a></dt>
<dd><p>Content of the response, in bytes.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.cookies">
<code class="descname">cookies</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>A CookieJar of Cookies the server sent back.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.elapsed">
<code class="descname">elapsed</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.elapsed" title="Permalink to this definition">¶</a></dt>
<dd><p>The amount of time elapsed between sending the request
and the arrival of the response (as a timedelta).
This property specifically measures the time taken between sending
the first byte of the request and finishing parsing the headers. It
is therefore unaffected by consuming the response content or the
value of the <code class="docutils literal"><span class="pre">stream</span></code> keyword argument.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.encoding">
<code class="descname">encoding</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Encoding to decode with when accessing r.text.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.headers">
<code class="descname">headers</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.headers" title="Permalink to this definition">¶</a></dt>
<dd><p>Case-insensitive Dictionary of Response Headers.
For example, <code class="docutils literal"><span class="pre">headers['content-encoding']</span></code> will return the
value of a <code class="docutils literal"><span class="pre">'Content-Encoding'</span></code> response header.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.history">
<code class="descname">history</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.history" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> objects from
the history of the Request. Any redirect responses will end
up here. The list is sorted from the oldest to the most recent request.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.is_permanent_redirect">
<code class="descname">is_permanent_redirect</code><a class="headerlink" href="#requests.Response.is_permanent_redirect" title="Permalink to this definition">¶</a></dt>
<dd><p>True if this Response one of the permanent versions of redirect</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.is_redirect">
<code class="descname">is_redirect</code><a class="headerlink" href="#requests.Response.is_redirect" title="Permalink to this definition">¶</a></dt>
<dd><p>True if this Response is a well-formed HTTP redirect that could have
been processed automatically (by <a class="reference internal" href="#requests.Session.resolve_redirects" title="requests.Session.resolve_redirects"><code class="xref py py-meth docutils literal"><span class="pre">Session.resolve_redirects()</span></code></a>).</p>
</dd></dl>

<dl class="method">
<dt id="requests.Response.iter_content">
<code class="descname">iter_content</code><span class="sig-paren">(</span><em>chunk_size=1</em>, <em>decode_unicode=False</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Response.iter_content" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterates over the response data.  When stream=True is set on the
request, this avoids reading the content at once into memory for
large responses.  The chunk size is the number of bytes it should
read into memory.  This is not necessarily the length of each item
returned as decoding can take place.</p>
<p>If decode_unicode is True, content will be decoded using the best
available encoding based on the response.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Response.iter_lines">
<code class="descname">iter_lines</code><span class="sig-paren">(</span><em>chunk_size=512</em>, <em>decode_unicode=None</em>, <em>delimiter=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Response.iter_lines" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterates over the response data, one line at a time.  When
stream=True is set on the request, this avoids reading the
content at once into memory for large responses.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This method is not reentrant safe.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="requests.Response.json">
<code class="descname">json</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Response.json" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the json-encoded content of a response, if any.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">json.loads</span></code> takes.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.links">
<code class="descname">links</code><a class="headerlink" href="#requests.Response.links" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the parsed header links of the response, if any.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Response.raise_for_status">
<code class="descname">raise_for_status</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.Response.raise_for_status" title="Permalink to this definition">¶</a></dt>
<dd><p>Raises stored <code class="xref py py-class docutils literal"><span class="pre">HTTPError</span></code>, if one occurred.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.raw">
<code class="descname">raw</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.raw" title="Permalink to this definition">¶</a></dt>
<dd><p>File-like object representation of response (for advanced usage).
Use of <code class="docutils literal"><span class="pre">raw</span></code> requires that <code class="docutils literal"><span class="pre">stream=True</span></code> be set on the request.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.reason">
<code class="descname">reason</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.reason" title="Permalink to this definition">¶</a></dt>
<dd><p>Textual reason of responded HTTP Status, e.g. &#8220;Not Found&#8221; or &#8220;OK&#8221;.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.request">
<code class="descname">request</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.request" title="Permalink to this definition">¶</a></dt>
<dd><p>The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> object to which this
is a response.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.status_code">
<code class="descname">status_code</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.status_code" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer Code of responded HTTP Status, e.g. 404 or 200.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.text">
<code class="descname">text</code><a class="headerlink" href="#requests.Response.text" title="Permalink to this definition">¶</a></dt>
<dd><p>Content of the response, in unicode.</p>
<p>If Response.encoding is None, encoding will be guessed using
<code class="docutils literal"><span class="pre">chardet</span></code>.</p>
<p>The encoding of the response content is determined based solely on HTTP
headers, following RFC 2616 to the letter. If you can take advantage of
non-HTTP knowledge to make a better guess at the encoding, you should
set <code class="docutils literal"><span class="pre">r.encoding</span></code> appropriately before accessing this property.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Response.url">
<code class="descname">url</code><em class="property"> = None</em><a class="headerlink" href="#requests.Response.url" title="Permalink to this definition">¶</a></dt>
<dd><p>Final URL location of Response.</p>
</dd></dl>

</dd></dl>

</div>
</div>
<div class="section" id="request-sessions">
<h4>Request Sessions<a class="headerlink" href="#request-sessions" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="requests.Session">
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Session</code><a class="headerlink" href="#requests.Session" title="Permalink to this definition">¶</a></dt>
<dd><p>A Requests session.</p>
<p>Provides cookie persistence, connection-pooling, and configuration.</p>
<p>Basic Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>Or as a context manager:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span> <span class="k">as</span> <span class="n">s</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="requests.Session.auth">
<code class="descname">auth</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.auth" title="Permalink to this definition">¶</a></dt>
<dd><p>Default Authentication tuple or object to attach to
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.cert">
<code class="descname">cert</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.cert" title="Permalink to this definition">¶</a></dt>
<dd><p>SSL certificate default.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.close">
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes all adapters and as such the session</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.cookies">
<code class="descname">cookies</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>A CookieJar containing all currently outstanding cookies set on this
session. By default it is a
<a class="reference internal" href="#requests.cookies.RequestsCookieJar" title="requests.cookies.RequestsCookieJar"><code class="xref py py-class docutils literal"><span class="pre">RequestsCookieJar</span></code></a>, but
may be any other <code class="docutils literal"><span class="pre">cookielib.CookieJar</span></code> compatible object.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.delete">
<code class="descname">delete</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a DELETE request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.get">
<code class="descname">get</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a GET request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.get_adapter">
<code class="descname">get_adapter</code><span class="sig-paren">(</span><em>url</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.get_adapter" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the appropriate connection adapter for the given URL.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.head">
<code class="descname">head</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.head" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a HEAD request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.headers">
<code class="descname">headers</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.headers" title="Permalink to this definition">¶</a></dt>
<dd><p>A case-insensitive dictionary of headers to be sent on each
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> sent from this
<a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a>.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.hooks">
<code class="descname">hooks</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.hooks" title="Permalink to this definition">¶</a></dt>
<dd><p>Event-handling hooks.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.max_redirects">
<code class="descname">max_redirects</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.max_redirects" title="Permalink to this definition">¶</a></dt>
<dd><p>Maximum number of redirects allowed. If the request exceeds this
limit, a <code class="xref py py-class docutils literal"><span class="pre">TooManyRedirects</span></code> exception is raised.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.merge_environment_settings">
<code class="descname">merge_environment_settings</code><span class="sig-paren">(</span><em>url</em>, <em>proxies</em>, <em>stream</em>, <em>verify</em>, <em>cert</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.merge_environment_settings" title="Permalink to this definition">¶</a></dt>
<dd><p>Check the environment and merge it with some settings.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.mount">
<code class="descname">mount</code><span class="sig-paren">(</span><em>prefix</em>, <em>adapter</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.mount" title="Permalink to this definition">¶</a></dt>
<dd><p>Registers a connection adapter to a prefix.</p>
<p>Adapters are sorted in descending order by key length.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.options">
<code class="descname">options</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.options" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a OPTIONS request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.params">
<code class="descname">params</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.params" title="Permalink to this definition">¶</a></dt>
<dd><p>Dictionary of querystring data to attach to each
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>. The dictionary values may be lists for
representing multivalued query parameters.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.patch">
<code class="descname">patch</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.patch" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a PATCH request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.post">
<code class="descname">post</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>json=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.post" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a POST request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.prepare_request">
<code class="descname">prepare_request</code><span class="sig-paren">(</span><em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.prepare_request" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> for
transmission and returns it. The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> has settings
merged from the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> instance and those of the
<a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>request</strong> &#8211; <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> instance to prepare with this
session&#8217;s settings.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.proxies">
<code class="descname">proxies</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.proxies" title="Permalink to this definition">¶</a></dt>
<dd><p>Dictionary mapping protocol or protocol and host to the URL of the proxy
(e.g. {&#8216;http&#8217;: &#8216;foo.bar:3128&#8217;, &#8216;http://host.name&#8217;: &#8216;foo.bar:4012&#8217;}) to
be used on each <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.put">
<code class="descname">put</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.put" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a PUT request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.rebuild_auth">
<code class="descname">rebuild_auth</code><span class="sig-paren">(</span><em>prepared_request</em>, <em>response</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.rebuild_auth" title="Permalink to this definition">¶</a></dt>
<dd><p>When being redirected we may want to strip authentication from the
request to avoid leaking credentials. This method intelligently removes
and reapplies authentication where possible to avoid credential loss.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.rebuild_proxies">
<code class="descname">rebuild_proxies</code><span class="sig-paren">(</span><em>prepared_request</em>, <em>proxies</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.rebuild_proxies" title="Permalink to this definition">¶</a></dt>
<dd><p>This method re-evaluates the proxy configuration by considering the
environment variables. If we are redirected to a URL covered by
NO_PROXY, we strip the proxy configuration. Otherwise, we set missing
proxy keys for this URL (in case they were stripped by a previous
redirect).</p>
<p>This method also replaces the Proxy-Authorization header where
necessary.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.request">
<code class="descname">request</code><span class="sig-paren">(</span><em>method</em>, <em>url</em>, <em>params=None</em>, <em>data=None</em>, <em>headers=None</em>, <em>cookies=None</em>, <em>files=None</em>, <em>auth=None</em>, <em>timeout=None</em>, <em>allow_redirects=True</em>, <em>proxies=None</em>, <em>hooks=None</em>, <em>stream=None</em>, <em>verify=None</em>, <em>cert=None</em>, <em>json=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.request" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>, prepares it and sends it.
Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>method</strong> &#8211; method for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>params</strong> &#8211; (optional) Dictionary or bytes to be sent in the query
string for the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send
in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json to send in the body of the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>headers</strong> &#8211; (optional) Dictionary of HTTP Headers to send with the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>cookies</strong> &#8211; (optional) Dict or CookieJar object to send with the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>files</strong> &#8211; (optional) Dictionary of <code class="docutils literal"><span class="pre">'filename':</span> <span class="pre">file-like-objects</span></code>
for multipart encoding upload.</li>
<li><strong>auth</strong> &#8211; (optional) Auth tuple or callable to enable
Basic/Digest/Custom HTTP Auth.</li>
<li><strong>timeout</strong> (<em>float or tuple</em>) &#8211; (optional) How long to wait for the server to send
data before giving up, as a float, or a <a class="reference internal" href="index.html#timeouts"><span>(connect timeout,
read timeout)</span></a> tuple.</li>
<li><strong>allow_redirects</strong> (<em>bool</em>) &#8211; (optional) Set to True by default.</li>
<li><strong>proxies</strong> &#8211; (optional) Dictionary mapping protocol or protocol and
hostname to the URL of the proxy.</li>
<li><strong>stream</strong> &#8211; (optional) whether to immediately download the response
content. Defaults to <code class="docutils literal"><span class="pre">False</span></code>.</li>
<li><strong>verify</strong> &#8211; (optional) whether the SSL cert will be verified.
A CA_BUNDLE path can also be provided. Defaults to <code class="docutils literal"><span class="pre">True</span></code>.</li>
<li><strong>cert</strong> &#8211; (optional) if String, path to ssl client cert file (.pem).
If Tuple, (&#8216;cert&#8217;, &#8216;key&#8217;) pair.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.Session.resolve_redirects">
<code class="descname">resolve_redirects</code><span class="sig-paren">(</span><em>resp</em>, <em>req</em>, <em>stream=False</em>, <em>timeout=None</em>, <em>verify=True</em>, <em>cert=None</em>, <em>proxies=None</em>, <em>**adapter_kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.resolve_redirects" title="Permalink to this definition">¶</a></dt>
<dd><p>Receives a Response. Returns a generator of Responses.</p>
</dd></dl>

<dl class="method">
<dt id="requests.Session.send">
<code class="descname">send</code><span class="sig-paren">(</span><em>request</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.Session.send" title="Permalink to this definition">¶</a></dt>
<dd><p>Send a given PreparedRequest.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.stream">
<code class="descname">stream</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.stream" title="Permalink to this definition">¶</a></dt>
<dd><p>Stream response content default.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.trust_env">
<code class="descname">trust_env</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.trust_env" title="Permalink to this definition">¶</a></dt>
<dd><p>Trust environment settings for proxy configuration, default
authentication and similar.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.Session.verify">
<code class="descname">verify</code><em class="property"> = None</em><a class="headerlink" href="#requests.Session.verify" title="Permalink to this definition">¶</a></dt>
<dd><p>SSL Verification default.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="requests.adapters.HTTPAdapter">
<em class="property">class </em><code class="descclassname">requests.adapters.</code><code class="descname">HTTPAdapter</code><span class="sig-paren">(</span><em>pool_connections=10</em>, <em>pool_maxsize=10</em>, <em>max_retries=0</em>, <em>pool_block=False</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter" title="Permalink to this definition">¶</a></dt>
<dd><p>The built-in HTTP Adapter for urllib3.</p>
<p>Provides a general-case interface for Requests sessions to contact HTTP and
HTTPS urls by implementing the Transport Adapter interface. This class will
usually be created by the <a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a> class under the
covers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>pool_connections</strong> &#8211; The number of urllib3 connection pools to cache.</li>
<li><strong>pool_maxsize</strong> &#8211; The maximum number of connections to save in the pool.</li>
<li><strong>max_retries</strong> (<em>int</em>) &#8211; The maximum number of retries each connection
should attempt. Note, this applies only to failed DNS lookups, socket
connections and connection timeouts, never to requests where data has
made it to the server. By default, Requests does not retry failed
connections. If you need granular control over the conditions under
which we retry a request, import urllib3&#8217;s <code class="docutils literal"><span class="pre">Retry</span></code> class and pass
that instead.</li>
<li><strong>pool_block</strong> &#8211; Whether the connection pool should block for connections.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">adapters</span><span class="o">.</span><span class="n">HTTPAdapter</span><span class="p">(</span><span class="n">max_retries</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">mount</span><span class="p">(</span><span class="s1">&#39;http://&#39;</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
</pre></div>
</div>
<dl class="method">
<dt id="requests.adapters.HTTPAdapter.add_headers">
<code class="descname">add_headers</code><span class="sig-paren">(</span><em>request</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.add_headers" title="Permalink to this definition">¶</a></dt>
<dd><p>Add any headers needed by the connection. As of v2.0 this does
nothing by default, but is left for overriding by users that subclass
the <a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> to add headers to.</li>
<li><strong>kwargs</strong> &#8211; The keyword arguments from the call to send().</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.build_response">
<code class="descname">build_response</code><span class="sig-paren">(</span><em>req</em>, <em>resp</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.build_response" title="Permalink to this definition">¶</a></dt>
<dd><p>Builds a <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object from a urllib3
response. This should not be called from user code, and is only exposed
for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>req</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> used to generate the response.</li>
<li><strong>resp</strong> &#8211; The urllib3 response object.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.cert_verify">
<code class="descname">cert_verify</code><span class="sig-paren">(</span><em>conn</em>, <em>url</em>, <em>verify</em>, <em>cert</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.cert_verify" title="Permalink to this definition">¶</a></dt>
<dd><p>Verify a SSL certificate. This method should not be called from user
code, and is only exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; The urllib3 connection object associated with the cert.</li>
<li><strong>url</strong> &#8211; The requested URL.</li>
<li><strong>verify</strong> &#8211; Whether we should actually verify the certificate.</li>
<li><strong>cert</strong> &#8211; The SSL certificate to verify.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.close">
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Disposes of any internal state.</p>
<p>Currently, this just closes the PoolManager, which closes pooled
connections.</p>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.get_connection">
<code class="descname">get_connection</code><span class="sig-paren">(</span><em>url</em>, <em>proxies=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.get_connection" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a urllib3 connection for the given URL. This should not be
called from user code, and is only exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; The URL to connect to.</li>
<li><strong>proxies</strong> &#8211; (optional) A Requests-style dictionary of proxies used on this request.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.init_poolmanager">
<code class="descname">init_poolmanager</code><span class="sig-paren">(</span><em>connections</em>, <em>maxsize</em>, <em>block=False</em>, <em>**pool_kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.init_poolmanager" title="Permalink to this definition">¶</a></dt>
<dd><p>Initializes a urllib3 PoolManager.</p>
<p>This method should not be called from user code, and is only
exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>connections</strong> &#8211; The number of urllib3 connection pools to cache.</li>
<li><strong>maxsize</strong> &#8211; The maximum number of connections to save in the pool.</li>
<li><strong>block</strong> &#8211; Block when no free connections are available.</li>
<li><strong>pool_kwargs</strong> &#8211; Extra keyword arguments used to initialize the Pool Manager.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.proxy_headers">
<code class="descname">proxy_headers</code><span class="sig-paren">(</span><em>proxy</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.proxy_headers" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionary of the headers to add to any request sent
through a proxy. This works with urllib3 magic to ensure that they are
correctly sent to the proxy, rather than in a tunnelled request if
CONNECT is being used.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>proxies</strong> &#8211; The url of the proxy being used for this request.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.proxy_manager_for">
<code class="descname">proxy_manager_for</code><span class="sig-paren">(</span><em>proxy</em>, <em>**proxy_kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.proxy_manager_for" title="Permalink to this definition">¶</a></dt>
<dd><p>Return urllib3 ProxyManager for the given proxy.</p>
<p>This method should not be called from user code, and is only
exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>proxy</strong> &#8211; The proxy to return a urllib3 ProxyManager for.</li>
<li><strong>proxy_kwargs</strong> &#8211; Extra keyword arguments used to configure the Proxy Manager.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">ProxyManager</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.request_url">
<code class="descname">request_url</code><span class="sig-paren">(</span><em>request</em>, <em>proxies</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.request_url" title="Permalink to this definition">¶</a></dt>
<dd><p>Obtain the url to use when making the final request.</p>
<p>If the message is being sent through a HTTP proxy, the full URL has to
be used. Otherwise, we should only use the path portion of the URL.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> being sent.</li>
<li><strong>proxies</strong> &#8211; A dictionary of schemes or schemes and hosts to proxy URLs.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="requests.adapters.HTTPAdapter.send">
<code class="descname">send</code><span class="sig-paren">(</span><em>request</em>, <em>stream=False</em>, <em>timeout=None</em>, <em>verify=True</em>, <em>cert=None</em>, <em>proxies=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.adapters.HTTPAdapter.send" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends PreparedRequest object. Returns Response object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> being sent.</li>
<li><strong>stream</strong> &#8211; (optional) Whether to stream the request content.</li>
<li><strong>timeout</strong> (<em>float or tuple</em>) &#8211; (optional) How long to wait for the server to send
data before giving up, as a float, or a <a class="reference internal" href="index.html#timeouts"><span>(connect timeout,
read timeout)</span></a> tuple.</li>
<li><strong>verify</strong> &#8211; (optional) Whether to verify SSL certificates.</li>
<li><strong>cert</strong> &#8211; (optional) Any user-provided SSL certificate to be trusted.</li>
<li><strong>proxies</strong> &#8211; (optional) The proxies dictionary to apply to the request.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="authentication">
<h4>Authentication<a class="headerlink" href="#authentication" title="Permalink to this headline">¶</a></h4>
<dl class="class">
<dt id="requests.auth.AuthBase">
<em class="property">class </em><code class="descclassname">requests.auth.</code><code class="descname">AuthBase</code><a class="headerlink" href="#requests.auth.AuthBase" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class that all auth implementations derive from</p>
</dd></dl>

<dl class="class">
<dt id="requests.auth.HTTPBasicAuth">
<em class="property">class </em><code class="descclassname">requests.auth.</code><code class="descname">HTTPBasicAuth</code><span class="sig-paren">(</span><em>username</em>, <em>password</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.auth.HTTPBasicAuth" title="Permalink to this definition">¶</a></dt>
<dd><p>Attaches HTTP Basic Authentication to the given Request object.</p>
</dd></dl>

<dl class="class">
<dt id="requests.auth.HTTPProxyAuth">
<em class="property">class </em><code class="descclassname">requests.auth.</code><code class="descname">HTTPProxyAuth</code><span class="sig-paren">(</span><em>username</em>, <em>password</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.auth.HTTPProxyAuth" title="Permalink to this definition">¶</a></dt>
<dd><p>Attaches HTTP Proxy Authentication to a given Request object.</p>
</dd></dl>

<dl class="class">
<dt id="requests.auth.HTTPDigestAuth">
<em class="property">class </em><code class="descclassname">requests.auth.</code><code class="descname">HTTPDigestAuth</code><span class="sig-paren">(</span><em>username</em>, <em>password</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.auth.HTTPDigestAuth" title="Permalink to this definition">¶</a></dt>
<dd><p>Attaches HTTP Digest Authentication to the given Request object.</p>
</dd></dl>

<div class="section" id="exceptions">
<h5>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h5>
<dl class="exception">
<dt id="requests.exceptions.RequestException">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">RequestException</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.RequestException" title="Permalink to this definition">¶</a></dt>
<dd><p>There was an ambiguous exception that occurred while handling your
request.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.ConnectionError">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">ConnectionError</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.ConnectionError" title="Permalink to this definition">¶</a></dt>
<dd><p>A Connection error occurred.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.HTTPError">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">HTTPError</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.HTTPError" title="Permalink to this definition">¶</a></dt>
<dd><p>An HTTP error occurred.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.URLRequired">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">URLRequired</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.URLRequired" title="Permalink to this definition">¶</a></dt>
<dd><p>A valid URL is required to make a request.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.TooManyRedirects">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">TooManyRedirects</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.TooManyRedirects" title="Permalink to this definition">¶</a></dt>
<dd><p>Too many redirects.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.ConnectTimeout">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">ConnectTimeout</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.ConnectTimeout" title="Permalink to this definition">¶</a></dt>
<dd><p>The request timed out while trying to connect to the remote server.</p>
<p>Requests that produced this error are safe to retry.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.ReadTimeout">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">ReadTimeout</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.ReadTimeout" title="Permalink to this definition">¶</a></dt>
<dd><p>The server did not send any data in the allotted amount of time.</p>
</dd></dl>

<dl class="exception">
<dt id="requests.exceptions.Timeout">
<em class="property">exception </em><code class="descclassname">requests.exceptions.</code><code class="descname">Timeout</code><span class="sig-paren">(</span><em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.exceptions.Timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>The request timed out.</p>
<p>Catching this error will catch both
<a class="reference internal" href="#requests.exceptions.ConnectTimeout" title="requests.exceptions.ConnectTimeout"><code class="xref py py-exc docutils literal"><span class="pre">ConnectTimeout</span></code></a> and
<a class="reference internal" href="#requests.exceptions.ReadTimeout" title="requests.exceptions.ReadTimeout"><code class="xref py py-exc docutils literal"><span class="pre">ReadTimeout</span></code></a> errors.</p>
</dd></dl>

</div>
<div class="section" id="status-code-lookup">
<h5>Status Code Lookup<a class="headerlink" href="#status-code-lookup" title="Permalink to this headline">¶</a></h5>
<dl class="function">
<dt id="requests.codes">
<code class="descclassname">requests.</code><code class="descname">codes</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.codes" title="Permalink to this definition">¶</a></dt>
<dd><p>Dictionary lookup object.</p>
</dd></dl>

<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="p">[</span><span class="s1">&#39;temporary_redirect&#39;</span><span class="p">]</span>
<span class="go">307</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="o">.</span><span class="n">teapot</span>
<span class="go">418</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">requests</span><span class="o">.</span><span class="n">codes</span><span class="p">[</span><span class="s1">&#39;\o/&#39;</span><span class="p">]</span>
<span class="go">200</span>
</pre></div>
</div>
</div>
<div class="section" id="cookies">
<span id="api-cookies"></span><h5>Cookies<a class="headerlink" href="#cookies" title="Permalink to this headline">¶</a></h5>
<dl class="function">
<dt id="requests.utils.dict_from_cookiejar">
<code class="descclassname">requests.utils.</code><code class="descname">dict_from_cookiejar</code><span class="sig-paren">(</span><em>cj</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.dict_from_cookiejar" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a key/value dictionary from a CookieJar.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>cj</strong> &#8211; CookieJar object to extract cookies from.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.utils.cookiejar_from_dict">
<code class="descclassname">requests.utils.</code><code class="descname">cookiejar_from_dict</code><span class="sig-paren">(</span><em>cookie_dict</em>, <em>cookiejar=None</em>, <em>overwrite=True</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.cookiejar_from_dict" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a CookieJar from a key/value dictionary.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>cookie_dict</strong> &#8211; Dict of key/values to insert into CookieJar.</li>
<li><strong>cookiejar</strong> &#8211; (optional) A cookiejar to add the cookies to.</li>
<li><strong>overwrite</strong> &#8211; (optional) If False, will not replace cookies
already in the jar with new ones.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.utils.add_dict_to_cookiejar">
<code class="descclassname">requests.utils.</code><code class="descname">add_dict_to_cookiejar</code><span class="sig-paren">(</span><em>cj</em>, <em>cookie_dict</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.add_dict_to_cookiejar" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a CookieJar from a key/value dictionary.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>cj</strong> &#8211; CookieJar to insert cookies into.</li>
<li><strong>cookie_dict</strong> &#8211; Dict of key/values to insert into CookieJar.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="class">
<dt id="requests.cookies.RequestsCookieJar">
<em class="property">class </em><code class="descclassname">requests.cookies.</code><code class="descname">RequestsCookieJar</code><span class="sig-paren">(</span><em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar" title="Permalink to this definition">¶</a></dt>
<dd><p>Compatibility class; is a cookielib.CookieJar, but exposes a dict
interface.</p>
<p>This is the CookieJar we create by default for requests and sessions that
don&#8217;t specify one, since some clients may expect response.cookies and
session.cookies to support dict operations.</p>
<p>Requests does not use the dict interface internally; it&#8217;s just for
compatibility with external client code. All requests code should work
out of the box with externally provided instances of <code class="docutils literal"><span class="pre">CookieJar</span></code>, e.g.
<code class="docutils literal"><span class="pre">LWPCookieJar</span></code> and <code class="docutils literal"><span class="pre">FileCookieJar</span></code>.</p>
<p>Unlike a regular CookieJar, this class is pickleable.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">dictionary operations that are normally O(1) may be O(n).</p>
</div>
<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.add_cookie_header">
<code class="descname">add_cookie_header</code><span class="sig-paren">(</span><em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.add_cookie_header" title="Permalink to this definition">¶</a></dt>
<dd><p>Add correct Cookie: header to request (urllib2.Request object).</p>
<p>The Cookie2 header is also added unless policy.hide_cookie2 is true.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.clear">
<code class="descname">clear</code><span class="sig-paren">(</span><em>domain=None</em>, <em>path=None</em>, <em>name=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear some cookies.</p>
<p>Invoking this method without arguments will clear all cookies.  If
given a single argument, only cookies belonging to that domain will be
removed.  If given two arguments, cookies belonging to the specified
path within that domain are removed.  If given three arguments, then
the cookie with the specified name, path and domain is removed.</p>
<p>Raises KeyError if no matching cookie exists.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.clear_expired_cookies">
<code class="descname">clear_expired_cookies</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.clear_expired_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>Discard all expired cookies.</p>
<p>You probably don&#8217;t need to call this method: expired cookies are never
sent back to the server (provided you&#8217;re using DefaultCookiePolicy),
this method is called by CookieJar itself every so often, and the
.save() method won&#8217;t save expired cookies anyway (unless you ask
otherwise by passing a true ignore_expires argument).</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.clear_session_cookies">
<code class="descname">clear_session_cookies</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.clear_session_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>Discard all session cookies.</p>
<p>Note that the .save() method won&#8217;t save session cookies anyway, unless
you ask otherwise by passing a true ignore_discard argument.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.copy">
<code class="descname">copy</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.copy" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a copy of this RequestsCookieJar.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.extract_cookies">
<code class="descname">extract_cookies</code><span class="sig-paren">(</span><em>response</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.extract_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>Extract cookies from response, where allowable given the request.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.get">
<code class="descname">get</code><span class="sig-paren">(</span><em>name</em>, <em>default=None</em>, <em>domain=None</em>, <em>path=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like get() that also supports optional domain and path args in
order to resolve naming collisions from using one cookie jar over
multiple domains.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">operation is O(n), not O(1).</p>
</div>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.get_dict">
<code class="descname">get_dict</code><span class="sig-paren">(</span><em>domain=None</em>, <em>path=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.get_dict" title="Permalink to this definition">¶</a></dt>
<dd><p>Takes as an argument an optional domain and path and returns a plain
old Python dict of name-value pairs of cookies that meet the
requirements.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.items">
<code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.items" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like items() that returns a list of name-value tuples from the
jar. See keys() and values(). Allows client-code to call
<code class="docutils literal"><span class="pre">dict(RequestsCookieJar)</span></code> and get a vanilla python dict of key value
pairs.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.iteritems">
<code class="descname">iteritems</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.iteritems" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like iteritems() that returns an iterator of name-value tuples
from the jar. See iterkeys() and itervalues().</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.iterkeys">
<code class="descname">iterkeys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.iterkeys" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like iterkeys() that returns an iterator of names of cookies
from the jar. See itervalues() and iteritems().</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.itervalues">
<code class="descname">itervalues</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.itervalues" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like itervalues() that returns an iterator of values of cookies
from the jar. See iterkeys() and iteritems().</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.keys">
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.keys" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like keys() that returns a list of names of cookies from the
jar. See values() and items().</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.list_domains">
<code class="descname">list_domains</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.list_domains" title="Permalink to this definition">¶</a></dt>
<dd><p>Utility method to list all the domains in the jar.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.list_paths">
<code class="descname">list_paths</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.list_paths" title="Permalink to this definition">¶</a></dt>
<dd><p>Utility method to list all the paths in the jar.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.make_cookies">
<code class="descname">make_cookies</code><span class="sig-paren">(</span><em>response</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.make_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>Return sequence of Cookie objects extracted from response object.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.multiple_domains">
<code class="descname">multiple_domains</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.multiple_domains" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if there are multiple domains in the jar.
Returns False otherwise.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.pop">
<code class="descname">pop</code><span class="sig-paren">(</span><em>k</em><span class="optional">[</span>, <em>d</em><span class="optional">]</span><span class="sig-paren">)</span> &rarr; v, remove specified key and return the corresponding value.<a class="headerlink" href="#requests.cookies.RequestsCookieJar.pop" title="Permalink to this definition">¶</a></dt>
<dd><p>If key is not found, d is returned if given, otherwise KeyError is raised.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.popitem">
<code class="descname">popitem</code><span class="sig-paren">(</span><span class="sig-paren">)</span> &rarr; (k, v), remove and return some (key, value) pair<a class="headerlink" href="#requests.cookies.RequestsCookieJar.popitem" title="Permalink to this definition">¶</a></dt>
<dd><p>as a 2-tuple; but raise KeyError if D is empty.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.set">
<code class="descname">set</code><span class="sig-paren">(</span><em>name</em>, <em>value</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.set" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like set() that also supports optional domain and path args in
order to resolve naming collisions from using one cookie jar over
multiple domains.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.set_cookie_if_ok">
<code class="descname">set_cookie_if_ok</code><span class="sig-paren">(</span><em>cookie</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.set_cookie_if_ok" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a cookie if policy says it&#8217;s OK to do so.</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.setdefault">
<code class="descname">setdefault</code><span class="sig-paren">(</span><em>k</em><span class="optional">[</span>, <em>d</em><span class="optional">]</span><span class="sig-paren">)</span> &rarr; D.get(k,d), also set D[k]=d if k not in D<a class="headerlink" href="#requests.cookies.RequestsCookieJar.setdefault" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.update">
<code class="descname">update</code><span class="sig-paren">(</span><em>other</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Updates this jar with cookies from another CookieJar or dict-like</p>
</dd></dl>

<dl class="method">
<dt id="requests.cookies.RequestsCookieJar.values">
<code class="descname">values</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#requests.cookies.RequestsCookieJar.values" title="Permalink to this definition">¶</a></dt>
<dd><p>Dict-like values() that returns a list of values of cookies from the
jar. See keys() and items().</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="requests.cookies.CookieConflictError">
<em class="property">class </em><code class="descclassname">requests.cookies.</code><code class="descname">CookieConflictError</code><a class="headerlink" href="#requests.cookies.CookieConflictError" title="Permalink to this definition">¶</a></dt>
<dd><p>There are two cookies that meet the criteria specified in the cookie jar.
Use .get and .set and include domain and path args in order to be more specific.</p>
</dd></dl>

</div>
<div class="section" id="encodings">
<h5>Encodings<a class="headerlink" href="#encodings" title="Permalink to this headline">¶</a></h5>
<dl class="function">
<dt id="requests.utils.get_encodings_from_content">
<code class="descclassname">requests.utils.</code><code class="descname">get_encodings_from_content</code><span class="sig-paren">(</span><em>content</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.get_encodings_from_content" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns encodings from given content string.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>content</strong> &#8211; bytestring to extract encodings from.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.utils.get_encoding_from_headers">
<code class="descclassname">requests.utils.</code><code class="descname">get_encoding_from_headers</code><span class="sig-paren">(</span><em>headers</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.get_encoding_from_headers" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns encodings from given HTTP Header Dict.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>headers</strong> &#8211; dictionary to extract encoding from.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="requests.utils.get_unicode_from_response">
<code class="descclassname">requests.utils.</code><code class="descname">get_unicode_from_response</code><span class="sig-paren">(</span><em>r</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.utils.get_unicode_from_response" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the requested content back in unicode.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>r</strong> &#8211; Response object to get unicode content from.</td>
</tr>
</tbody>
</table>
<p>Tried:</p>
<ol class="arabic simple">
<li>charset from content-type</li>
<li>fall back and replace all unicode characters</li>
</ol>
</dd></dl>

</div>
<div class="section" id="classes">
<h5>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h5>
<dl class="class">
<dt>
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Response</code></dt>
<dd><p>The <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object, which contains a
server&#8217;s response to an HTTP request.</p>
<dl class="attribute">
<dt>
<code class="descname">apparent_encoding</code></dt>
<dd><p>The apparent encoding, provided by the chardet library</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>Releases the connection back to the pool. Once this method has been
called the underlying <code class="docutils literal"><span class="pre">raw</span></code> object must not be accessed again.</p>
<p><em>Note: Should not normally need to be called explicitly.</em></p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">content</code></dt>
<dd><p>Content of the response, in bytes.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">cookies</code><em class="property"> = None</em></dt>
<dd><p>A CookieJar of Cookies the server sent back.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">elapsed</code><em class="property"> = None</em></dt>
<dd><p>The amount of time elapsed between sending the request
and the arrival of the response (as a timedelta).
This property specifically measures the time taken between sending
the first byte of the request and finishing parsing the headers. It
is therefore unaffected by consuming the response content or the
value of the <code class="docutils literal"><span class="pre">stream</span></code> keyword argument.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">encoding</code><em class="property"> = None</em></dt>
<dd><p>Encoding to decode with when accessing r.text.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">headers</code><em class="property"> = None</em></dt>
<dd><p>Case-insensitive Dictionary of Response Headers.
For example, <code class="docutils literal"><span class="pre">headers['content-encoding']</span></code> will return the
value of a <code class="docutils literal"><span class="pre">'Content-Encoding'</span></code> response header.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">history</code><em class="property"> = None</em></dt>
<dd><p>A list of <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> objects from
the history of the Request. Any redirect responses will end
up here. The list is sorted from the oldest to the most recent request.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">is_permanent_redirect</code></dt>
<dd><p>True if this Response one of the permanent versions of redirect</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">is_redirect</code></dt>
<dd><p>True if this Response is a well-formed HTTP redirect that could have
been processed automatically (by <a class="reference internal" href="#requests.Session.resolve_redirects" title="requests.Session.resolve_redirects"><code class="xref py py-meth docutils literal"><span class="pre">Session.resolve_redirects()</span></code></a>).</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">iter_content</code><span class="sig-paren">(</span><em>chunk_size=1</em>, <em>decode_unicode=False</em><span class="sig-paren">)</span></dt>
<dd><p>Iterates over the response data.  When stream=True is set on the
request, this avoids reading the content at once into memory for
large responses.  The chunk size is the number of bytes it should
read into memory.  This is not necessarily the length of each item
returned as decoding can take place.</p>
<p>If decode_unicode is True, content will be decoded using the best
available encoding based on the response.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">iter_lines</code><span class="sig-paren">(</span><em>chunk_size=512</em>, <em>decode_unicode=None</em>, <em>delimiter=None</em><span class="sig-paren">)</span></dt>
<dd><p>Iterates over the response data, one line at a time.  When
stream=True is set on the request, this avoids reading the
content at once into memory for large responses.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This method is not reentrant safe.</p>
</div>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">json</code><span class="sig-paren">(</span><em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Returns the json-encoded content of a response, if any.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">json.loads</span></code> takes.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">links</code></dt>
<dd><p>Returns the parsed header links of the response, if any.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">raise_for_status</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>Raises stored <code class="xref py py-class docutils literal"><span class="pre">HTTPError</span></code>, if one occurred.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">raw</code><em class="property"> = None</em></dt>
<dd><p>File-like object representation of response (for advanced usage).
Use of <code class="docutils literal"><span class="pre">raw</span></code> requires that <code class="docutils literal"><span class="pre">stream=True</span></code> be set on the request.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">reason</code><em class="property"> = None</em></dt>
<dd><p>Textual reason of responded HTTP Status, e.g. &#8220;Not Found&#8221; or &#8220;OK&#8221;.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">request</code><em class="property"> = None</em></dt>
<dd><p>The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> object to which this
is a response.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">status_code</code><em class="property"> = None</em></dt>
<dd><p>Integer Code of responded HTTP Status, e.g. 404 or 200.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">text</code></dt>
<dd><p>Content of the response, in unicode.</p>
<p>If Response.encoding is None, encoding will be guessed using
<code class="docutils literal"><span class="pre">chardet</span></code>.</p>
<p>The encoding of the response content is determined based solely on HTTP
headers, following RFC 2616 to the letter. If you can take advantage of
non-HTTP knowledge to make a better guess at the encoding, you should
set <code class="docutils literal"><span class="pre">r.encoding</span></code> appropriately before accessing this property.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">url</code><em class="property"> = None</em></dt>
<dd><p>Final URL location of Response.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt>
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Request</code><span class="sig-paren">(</span><em>method=None</em>, <em>url=None</em>, <em>headers=None</em>, <em>files=None</em>, <em>data=None</em>, <em>params=None</em>, <em>auth=None</em>, <em>cookies=None</em>, <em>hooks=None</em>, <em>json=None</em><span class="sig-paren">)</span></dt>
<dd><p>A user-created <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</p>
<p>Used to prepare a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a>, which is sent to the server.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>method</strong> &#8211; HTTP method to use.</li>
<li><strong>url</strong> &#8211; URL to send.</li>
<li><strong>headers</strong> &#8211; dictionary of headers to send.</li>
<li><strong>files</strong> &#8211; dictionary of {filename: fileobject} files to multipart upload.</li>
<li><strong>data</strong> &#8211; the body to attach to the request. If a dictionary is provided, form-encoding will take place.</li>
<li><strong>json</strong> &#8211; json for the body to attach to the request (if files or data is not specified).</li>
<li><strong>params</strong> &#8211; dictionary of URL parameters to append to the URL.</li>
<li><strong>auth</strong> &#8211; Auth handler or (user, pass) tuple.</li>
<li><strong>cookies</strong> &#8211; dictionary or CookieJar of cookies to attach to this request.</li>
<li><strong>hooks</strong> &#8211; dictionary of callback hooks, for internal usage.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span><span class="o">.</span><span class="n">prepare</span><span class="p">()</span>
<span class="go">&lt;PreparedRequest [GET]&gt;</span>
</pre></div>
</div>
<dl class="method">
<dt>
<code class="descname">deregister_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span></dt>
<dd><p>Deregister a previously registered hook.
Returns True if the hook existed, False if not.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">prepare</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> for transmission and returns it.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">register_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span></dt>
<dd><p>Properly register a hook.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="requests.PreparedRequest">
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">PreparedRequest</code><a class="headerlink" href="#requests.PreparedRequest" title="Permalink to this definition">¶</a></dt>
<dd><p>The fully mutable <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> object,
containing the exact bytes that will be sent to the server.</p>
<p>Generated from either a <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object or manually.</p>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">req</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Request</span><span class="p">(</span><span class="s1">&#39;GET&#39;</span><span class="p">,</span> <span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">prepare</span><span class="p">()</span>
<span class="go">&lt;PreparedRequest [GET]&gt;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">r</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="requests.PreparedRequest.body">
<code class="descname">body</code><em class="property"> = None</em><a class="headerlink" href="#requests.PreparedRequest.body" title="Permalink to this definition">¶</a></dt>
<dd><p>request body to send to the server.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.deregister_hook">
<code class="descname">deregister_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.deregister_hook" title="Permalink to this definition">¶</a></dt>
<dd><p>Deregister a previously registered hook.
Returns True if the hook existed, False if not.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.PreparedRequest.headers">
<code class="descname">headers</code><em class="property"> = None</em><a class="headerlink" href="#requests.PreparedRequest.headers" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary of HTTP headers.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.PreparedRequest.hooks">
<code class="descname">hooks</code><em class="property"> = None</em><a class="headerlink" href="#requests.PreparedRequest.hooks" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary of callback hooks, for internal usage.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.PreparedRequest.method">
<code class="descname">method</code><em class="property"> = None</em><a class="headerlink" href="#requests.PreparedRequest.method" title="Permalink to this definition">¶</a></dt>
<dd><p>HTTP verb to send to the server.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.PreparedRequest.path_url">
<code class="descname">path_url</code><a class="headerlink" href="#requests.PreparedRequest.path_url" title="Permalink to this definition">¶</a></dt>
<dd><p>Build the path URL to use.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare">
<code class="descname">prepare</code><span class="sig-paren">(</span><em>method=None</em>, <em>url=None</em>, <em>headers=None</em>, <em>files=None</em>, <em>data=None</em>, <em>params=None</em>, <em>auth=None</em>, <em>cookies=None</em>, <em>hooks=None</em>, <em>json=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the entire request with the given parameters.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_auth">
<code class="descname">prepare_auth</code><span class="sig-paren">(</span><em>auth</em>, <em>url=''</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_auth" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP auth data.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_body">
<code class="descname">prepare_body</code><span class="sig-paren">(</span><em>data</em>, <em>files</em>, <em>json=None</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_body" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP body data.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_cookies">
<code class="descname">prepare_cookies</code><span class="sig-paren">(</span><em>cookies</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP cookie data.</p>
<p>This function eventually generates a <code class="docutils literal"><span class="pre">Cookie</span></code> header from the
given cookies using cookielib. Due to cookielib&#8217;s design, the header
will not be regenerated if it already exists, meaning this function
can only be called once for the life of the
<a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> object. Any subsequent calls
to <code class="docutils literal"><span class="pre">prepare_cookies</span></code> will have no actual effect, unless the &#8220;Cookie&#8221;
header is removed beforehand.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_headers">
<code class="descname">prepare_headers</code><span class="sig-paren">(</span><em>headers</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_headers" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP headers.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_hooks">
<code class="descname">prepare_hooks</code><span class="sig-paren">(</span><em>hooks</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_hooks" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given hooks.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_method">
<code class="descname">prepare_method</code><span class="sig-paren">(</span><em>method</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_method" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP method.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.prepare_url">
<code class="descname">prepare_url</code><span class="sig-paren">(</span><em>url</em>, <em>params</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.prepare_url" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepares the given HTTP URL.</p>
</dd></dl>

<dl class="method">
<dt id="requests.PreparedRequest.register_hook">
<code class="descname">register_hook</code><span class="sig-paren">(</span><em>event</em>, <em>hook</em><span class="sig-paren">)</span><a class="headerlink" href="#requests.PreparedRequest.register_hook" title="Permalink to this definition">¶</a></dt>
<dd><p>Properly register a hook.</p>
</dd></dl>

<dl class="attribute">
<dt id="requests.PreparedRequest.url">
<code class="descname">url</code><em class="property"> = None</em><a class="headerlink" href="#requests.PreparedRequest.url" title="Permalink to this definition">¶</a></dt>
<dd><p>HTTP URL to send the request to.</p>
</dd></dl>

</dd></dl>

<span class="target" id="sessionapi"></span><dl class="class">
<dt>
<em class="property">class </em><code class="descclassname">requests.</code><code class="descname">Session</code></dt>
<dd><p>A Requests session.</p>
<p>Provides cookie persistence, connection-pooling, and configuration.</p>
<p>Basic Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<p>Or as a context manager:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span> <span class="k">as</span> <span class="n">s</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/get&#39;</span><span class="p">)</span>
<span class="go">&lt;Response [200]&gt;</span>
</pre></div>
</div>
<dl class="attribute">
<dt>
<code class="descname">auth</code><em class="property"> = None</em></dt>
<dd><p>Default Authentication tuple or object to attach to
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">cert</code><em class="property"> = None</em></dt>
<dd><p>SSL certificate default.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>Closes all adapters and as such the session</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">cookies</code><em class="property"> = None</em></dt>
<dd><p>A CookieJar containing all currently outstanding cookies set on this
session. By default it is a
<a class="reference internal" href="#requests.cookies.RequestsCookieJar" title="requests.cookies.RequestsCookieJar"><code class="xref py py-class docutils literal"><span class="pre">RequestsCookieJar</span></code></a>, but
may be any other <code class="docutils literal"><span class="pre">cookielib.CookieJar</span></code> compatible object.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">delete</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a DELETE request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">get</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a GET request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">get_adapter</code><span class="sig-paren">(</span><em>url</em><span class="sig-paren">)</span></dt>
<dd><p>Returns the appropriate connection adapter for the given URL.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">head</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a HEAD request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">headers</code><em class="property"> = None</em></dt>
<dd><p>A case-insensitive dictionary of headers to be sent on each
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> sent from this
<a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a>.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">hooks</code><em class="property"> = None</em></dt>
<dd><p>Event-handling hooks.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">max_redirects</code><em class="property"> = None</em></dt>
<dd><p>Maximum number of redirects allowed. If the request exceeds this
limit, a <code class="xref py py-class docutils literal"><span class="pre">TooManyRedirects</span></code> exception is raised.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">merge_environment_settings</code><span class="sig-paren">(</span><em>url</em>, <em>proxies</em>, <em>stream</em>, <em>verify</em>, <em>cert</em><span class="sig-paren">)</span></dt>
<dd><p>Check the environment and merge it with some settings.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">mount</code><span class="sig-paren">(</span><em>prefix</em>, <em>adapter</em><span class="sig-paren">)</span></dt>
<dd><p>Registers a connection adapter to a prefix.</p>
<p>Adapters are sorted in descending order by key length.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">options</code><span class="sig-paren">(</span><em>url</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a OPTIONS request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">params</code><em class="property"> = None</em></dt>
<dd><p>Dictionary of querystring data to attach to each
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>. The dictionary values may be lists for
representing multivalued query parameters.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">patch</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a PATCH request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">post</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>json=None</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a POST request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">prepare_request</code><span class="sig-paren">(</span><em>request</em><span class="sig-paren">)</span></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> for
transmission and returns it. The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> has settings
merged from the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> instance and those of the
<a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>request</strong> &#8211; <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> instance to prepare with this
session&#8217;s settings.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">proxies</code><em class="property"> = None</em></dt>
<dd><p>Dictionary mapping protocol or protocol and host to the URL of the proxy
(e.g. {&#8216;http&#8217;: &#8216;foo.bar:3128&#8217;, &#8216;http://host.name&#8217;: &#8216;foo.bar:4012&#8217;}) to
be used on each <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">put</code><span class="sig-paren">(</span><em>url</em>, <em>data=None</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Sends a PUT request. Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>**kwargs</strong> &#8211; Optional arguments that <code class="docutils literal"><span class="pre">request</span></code> takes.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">rebuild_auth</code><span class="sig-paren">(</span><em>prepared_request</em>, <em>response</em><span class="sig-paren">)</span></dt>
<dd><p>When being redirected we may want to strip authentication from the
request to avoid leaking credentials. This method intelligently removes
and reapplies authentication where possible to avoid credential loss.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">rebuild_proxies</code><span class="sig-paren">(</span><em>prepared_request</em>, <em>proxies</em><span class="sig-paren">)</span></dt>
<dd><p>This method re-evaluates the proxy configuration by considering the
environment variables. If we are redirected to a URL covered by
NO_PROXY, we strip the proxy configuration. Otherwise, we set missing
proxy keys for this URL (in case they were stripped by a previous
redirect).</p>
<p>This method also replaces the Proxy-Authorization header where
necessary.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">request</code><span class="sig-paren">(</span><em>method</em>, <em>url</em>, <em>params=None</em>, <em>data=None</em>, <em>headers=None</em>, <em>cookies=None</em>, <em>files=None</em>, <em>auth=None</em>, <em>timeout=None</em>, <em>allow_redirects=True</em>, <em>proxies=None</em>, <em>hooks=None</em>, <em>stream=None</em>, <em>verify=None</em>, <em>cert=None</em>, <em>json=None</em><span class="sig-paren">)</span></dt>
<dd><p>Constructs a <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>, prepares it and sends it.
Returns <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>method</strong> &#8211; method for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>url</strong> &#8211; URL for the new <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a> object.</li>
<li><strong>params</strong> &#8211; (optional) Dictionary or bytes to be sent in the query
string for the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>data</strong> &#8211; (optional) Dictionary, bytes, or file-like object to send
in the body of the <a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>json</strong> &#8211; (optional) json to send in the body of the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>headers</strong> &#8211; (optional) Dictionary of HTTP Headers to send with the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>cookies</strong> &#8211; (optional) Dict or CookieJar object to send with the
<a class="reference internal" href="#requests.Request" title="requests.Request"><code class="xref py py-class docutils literal"><span class="pre">Request</span></code></a>.</li>
<li><strong>files</strong> &#8211; (optional) Dictionary of <code class="docutils literal"><span class="pre">'filename':</span> <span class="pre">file-like-objects</span></code>
for multipart encoding upload.</li>
<li><strong>auth</strong> &#8211; (optional) Auth tuple or callable to enable
Basic/Digest/Custom HTTP Auth.</li>
<li><strong>timeout</strong> (<em>float or tuple</em>) &#8211; (optional) How long to wait for the server to send
data before giving up, as a float, or a <a class="reference internal" href="index.html#timeouts"><span>(connect timeout,
read timeout)</span></a> tuple.</li>
<li><strong>allow_redirects</strong> (<em>bool</em>) &#8211; (optional) Set to True by default.</li>
<li><strong>proxies</strong> &#8211; (optional) Dictionary mapping protocol or protocol and
hostname to the URL of the proxy.</li>
<li><strong>stream</strong> &#8211; (optional) whether to immediately download the response
content. Defaults to <code class="docutils literal"><span class="pre">False</span></code>.</li>
<li><strong>verify</strong> &#8211; (optional) whether the SSL cert will be verified.
A CA_BUNDLE path can also be provided. Defaults to <code class="docutils literal"><span class="pre">True</span></code>.</li>
<li><strong>cert</strong> &#8211; (optional) if String, path to ssl client cert file (.pem).
If Tuple, (&#8216;cert&#8217;, &#8216;key&#8217;) pair.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">resolve_redirects</code><span class="sig-paren">(</span><em>resp</em>, <em>req</em>, <em>stream=False</em>, <em>timeout=None</em>, <em>verify=True</em>, <em>cert=None</em>, <em>proxies=None</em>, <em>**adapter_kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Receives a Response. Returns a generator of Responses.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">send</code><span class="sig-paren">(</span><em>request</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Send a given PreparedRequest.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">stream</code><em class="property"> = None</em></dt>
<dd><p>Stream response content default.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">trust_env</code><em class="property"> = None</em></dt>
<dd><p>Trust environment settings for proxy configuration, default
authentication and similar.</p>
</dd></dl>

<dl class="attribute">
<dt>
<code class="descname">verify</code><em class="property"> = None</em></dt>
<dd><p>SSL Verification default.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt>
<em class="property">class </em><code class="descclassname">requests.adapters.</code><code class="descname">HTTPAdapter</code><span class="sig-paren">(</span><em>pool_connections=10</em>, <em>pool_maxsize=10</em>, <em>max_retries=0</em>, <em>pool_block=False</em><span class="sig-paren">)</span></dt>
<dd><p>The built-in HTTP Adapter for urllib3.</p>
<p>Provides a general-case interface for Requests sessions to contact HTTP and
HTTPS urls by implementing the Transport Adapter interface. This class will
usually be created by the <a class="reference internal" href="#requests.Session" title="requests.Session"><code class="xref py py-class docutils literal"><span class="pre">Session</span></code></a> class under the
covers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>pool_connections</strong> &#8211; The number of urllib3 connection pools to cache.</li>
<li><strong>pool_maxsize</strong> &#8211; The maximum number of connections to save in the pool.</li>
<li><strong>max_retries</strong> (<em>int</em>) &#8211; The maximum number of retries each connection
should attempt. Note, this applies only to failed DNS lookups, socket
connections and connection timeouts, never to requests where data has
made it to the server. By default, Requests does not retry failed
connections. If you need granular control over the conditions under
which we retry a request, import urllib3&#8217;s <code class="docutils literal"><span class="pre">Retry</span></code> class and pass
that instead.</li>
<li><strong>pool_block</strong> &#8211; Whether the connection pool should block for connections.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>Usage:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">requests</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">adapters</span><span class="o">.</span><span class="n">HTTPAdapter</span><span class="p">(</span><span class="n">max_retries</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">mount</span><span class="p">(</span><span class="s1">&#39;http://&#39;</span><span class="p">,</span> <span class="n">a</span><span class="p">)</span>
</pre></div>
</div>
<dl class="method">
<dt>
<code class="descname">add_headers</code><span class="sig-paren">(</span><em>request</em>, <em>**kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Add any headers needed by the connection. As of v2.0 this does
nothing by default, but is left for overriding by users that subclass
the <a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> to add headers to.</li>
<li><strong>kwargs</strong> &#8211; The keyword arguments from the call to send().</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">build_response</code><span class="sig-paren">(</span><em>req</em>, <em>resp</em><span class="sig-paren">)</span></dt>
<dd><p>Builds a <a class="reference internal" href="#requests.Response" title="requests.Response"><code class="xref py py-class docutils literal"><span class="pre">Response</span></code></a> object from a urllib3
response. This should not be called from user code, and is only exposed
for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>req</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> used to generate the response.</li>
<li><strong>resp</strong> &#8211; The urllib3 response object.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">cert_verify</code><span class="sig-paren">(</span><em>conn</em>, <em>url</em>, <em>verify</em>, <em>cert</em><span class="sig-paren">)</span></dt>
<dd><p>Verify a SSL certificate. This method should not be called from user
code, and is only exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>conn</strong> &#8211; The urllib3 connection object associated with the cert.</li>
<li><strong>url</strong> &#8211; The requested URL.</li>
<li><strong>verify</strong> &#8211; Whether we should actually verify the certificate.</li>
<li><strong>cert</strong> &#8211; The SSL certificate to verify.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>Disposes of any internal state.</p>
<p>Currently, this just closes the PoolManager, which closes pooled
connections.</p>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">get_connection</code><span class="sig-paren">(</span><em>url</em>, <em>proxies=None</em><span class="sig-paren">)</span></dt>
<dd><p>Returns a urllib3 connection for the given URL. This should not be
called from user code, and is only exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>url</strong> &#8211; The URL to connect to.</li>
<li><strong>proxies</strong> &#8211; (optional) A Requests-style dictionary of proxies used on this request.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">init_poolmanager</code><span class="sig-paren">(</span><em>connections</em>, <em>maxsize</em>, <em>block=False</em>, <em>**pool_kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Initializes a urllib3 PoolManager.</p>
<p>This method should not be called from user code, and is only
exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>connections</strong> &#8211; The number of urllib3 connection pools to cache.</li>
<li><strong>maxsize</strong> &#8211; The maximum number of connections to save in the pool.</li>
<li><strong>block</strong> &#8211; Block when no free connections are available.</li>
<li><strong>pool_kwargs</strong> &#8211; Extra keyword arguments used to initialize the Pool Manager.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">proxy_headers</code><span class="sig-paren">(</span><em>proxy</em><span class="sig-paren">)</span></dt>
<dd><p>Returns a dictionary of the headers to add to any request sent
through a proxy. This works with urllib3 magic to ensure that they are
correctly sent to the proxy, rather than in a tunnelled request if
CONNECT is being used.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>proxies</strong> &#8211; The url of the proxy being used for this request.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">proxy_manager_for</code><span class="sig-paren">(</span><em>proxy</em>, <em>**proxy_kwargs</em><span class="sig-paren">)</span></dt>
<dd><p>Return urllib3 ProxyManager for the given proxy.</p>
<p>This method should not be called from user code, and is only
exposed for use when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>proxy</strong> &#8211; The proxy to return a urllib3 ProxyManager for.</li>
<li><strong>proxy_kwargs</strong> &#8211; Extra keyword arguments used to configure the Proxy Manager.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">ProxyManager</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">request_url</code><span class="sig-paren">(</span><em>request</em>, <em>proxies</em><span class="sig-paren">)</span></dt>
<dd><p>Obtain the url to use when making the final request.</p>
<p>If the message is being sent through a HTTP proxy, the full URL has to
be used. Otherwise, we should only use the path portion of the URL.</p>
<p>This should not be called from user code, and is only exposed for use
when subclassing the
<a class="reference internal" href="#requests.adapters.HTTPAdapter" title="requests.adapters.HTTPAdapter"><code class="xref py py-class docutils literal"><span class="pre">HTTPAdapter</span></code></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> being sent.</li>
<li><strong>proxies</strong> &#8211; A dictionary of schemes or schemes and hosts to proxy URLs.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt>
<code class="descname">send</code><span class="sig-paren">(</span><em>request</em>, <em>stream=False</em>, <em>timeout=None</em>, <em>verify=True</em>, <em>cert=None</em>, <em>proxies=None</em><span class="sig-paren">)</span></dt>
<dd><p>Sends PreparedRequest object. Returns Response object.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>request</strong> &#8211; The <a class="reference internal" href="#requests.PreparedRequest" title="requests.PreparedRequest"><code class="xref py py-class docutils literal"><span class="pre">PreparedRequest</span></code></a> being sent.</li>
<li><strong>stream</strong> &#8211; (optional) Whether to stream the request content.</li>
<li><strong>timeout</strong> (<em>float or tuple</em>) &#8211; (optional) How long to wait for the server to send
data before giving up, as a float, or a <a class="reference internal" href="index.html#timeouts"><span>(connect timeout,
read timeout)</span></a> tuple.</li>
<li><strong>verify</strong> &#8211; (optional) Whether to verify SSL certificates.</li>
<li><strong>cert</strong> &#8211; (optional) Any user-provided SSL certificate to be trusted.</li>
<li><strong>proxies</strong> &#8211; (optional) The proxies dictionary to apply to the request.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</dd></dl>

</div>
</div>
<div class="section" id="migrating-to-1-x">
<h4>Migrating to 1.x<a class="headerlink" href="#migrating-to-1-x" title="Permalink to this headline">¶</a></h4>
<p>This section details the main differences between 0.x and 1.x and is meant
to ease the pain of upgrading.</p>
<div class="section" id="api-changes">
<h5>API Changes<a class="headerlink" href="#api-changes" title="Permalink to this headline">¶</a></h5>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">Response.json</span></code> is now a callable and not a property of a response.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com/timeline.json&#39;</span><span class="p">)</span>
<span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>   <span class="c1"># This *call* raises an exception if JSON decoding fails</span>
</pre></div>
</div>
</li>
<li><p class="first">The <code class="docutils literal"><span class="pre">Session</span></code> API has changed. Sessions objects no longer take parameters.
<code class="docutils literal"><span class="pre">Session</span></code> is also now capitalized, but it can still be
instantiated with a lowercase <code class="docutils literal"><span class="pre">session</span></code> for backwards compatibility.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>    <span class="c1"># formerly, session took parameters</span>
<span class="n">s</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="n">auth</span>
<span class="n">s</span><span class="o">.</span><span class="n">headers</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">headers</span><span class="p">)</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/headers&#39;</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p class="first">All request hooks have been removed except &#8216;response&#8217;.</p>
</li>
<li><p class="first">Authentication helpers have been broken out into separate modules. See
<a class="reference external" href="#">requests-oauthlib</a> and <a class="reference external" href="#">requests-kerberos</a>.</p>
</li>
</ul>
<ul>
<li><p class="first">The parameter for streaming requests was changed from <code class="docutils literal"><span class="pre">prefetch</span></code> to
<code class="docutils literal"><span class="pre">stream</span></code> and the logic was inverted. In addition, <code class="docutils literal"><span class="pre">stream</span></code> is now
required for raw response reading.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="c1"># in 0.x, passing prefetch=False would accomplish the same thing</span>
<span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;https://github.com/timeline.json&#39;</span><span class="p">,</span> <span class="n">stream</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">for</span> <span class="n">chunk</span> <span class="ow">in</span> <span class="n">r</span><span class="o">.</span><span class="n">iter_content</span><span class="p">(</span><span class="mi">8192</span><span class="p">):</span>
    <span class="o">...</span>
</pre></div>
</div>
</li>
<li><p class="first">The <code class="docutils literal"><span class="pre">config</span></code> parameter to the requests method has been removed. Some of
these options are now configured on a <code class="docutils literal"><span class="pre">Session</span></code> such as keep-alive and
maximum number of redirects. The verbosity option should be handled by
configuring logging.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">requests</span>
<span class="kn">import</span> <span class="nn">logging</span>

<span class="c1"># these two lines enable debugging at httplib level (requests-&gt;urllib3-&gt;httplib)</span>
<span class="c1"># you will see the REQUEST, including HEADERS and DATA, and RESPONSE with HEADERS but without DATA.</span>
<span class="c1"># the only thing missing will be the response.body which is not logged.</span>
<span class="kn">import</span> <span class="nn">httplib</span>
<span class="n">httplib</span><span class="o">.</span><span class="n">HTTPConnection</span><span class="o">.</span><span class="n">debuglevel</span> <span class="o">=</span> <span class="mi">1</span>

<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">()</span> <span class="c1"># you need to initialize logging, otherwise you will not see anything from requests</span>
<span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">()</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>
<span class="n">requests_log</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;requests.packages.urllib3&quot;</span><span class="p">)</span>
<span class="n">requests_log</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>
<span class="n">requests_log</span><span class="o">.</span><span class="n">propagate</span> <span class="o">=</span> <span class="bp">True</span>

<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://httpbin.org/headers&#39;</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="licensing">
<h5>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h5>
<p>One key difference that has nothing to do with the API is a change in the
license from the <a class="reference external" href="#">ISC</a> license to the <a class="reference external" href="#">Apache 2.0</a> license. The Apache 2.0
license ensures that contributions to Requests are also covered by the Apache
2.0 license.</p>
</div>
</div>
<div class="section" id="migrating-to-2-x">
<h4>Migrating to 2.x<a class="headerlink" href="#migrating-to-2-x" title="Permalink to this headline">¶</a></h4>
<p>Compared with the 1.0 release, there were relatively few backwards
incompatible changes, but there are still a few issues to be aware of with
this major release.</p>
<p>For more details on the changes in this release including new APIs, links
to the relevant GitHub issues and some of the bug fixes, read Cory&#8217;s <a class="reference external" href="#">blog</a>
on the subject.</p>
<div class="section" id="id1">
<h5>API Changes<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h5>
<ul>
<li><p class="first">There were a couple changes to how Requests handles exceptions.
<code class="docutils literal"><span class="pre">RequestException</span></code> is now a subclass of <code class="docutils literal"><span class="pre">IOError</span></code> rather than
<code class="docutils literal"><span class="pre">RuntimeError</span></code> as that more accurately categorizes the type of error.
In addition, an invalid URL escape sequence now raises a subclass of
<code class="docutils literal"><span class="pre">RequestException</span></code> rather than a <code class="docutils literal"><span class="pre">ValueError</span></code>.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;http://%zz/&#39;</span><span class="p">)</span>   <span class="c1"># raises requests.exceptions.InvalidURL</span>
</pre></div>
</div>
<p>Lastly, <code class="docutils literal"><span class="pre">httplib.IncompleteRead</span></code> exceptions caused by incorrect chunked
encoding will now raise a Requests <code class="docutils literal"><span class="pre">ChunkedEncodingError</span></code> instead.</p>
</li>
<li><p class="first">The proxy API has changed slightly. The scheme for a proxy URL is now
required.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">proxies</span> <span class="o">=</span> <span class="p">{</span>
  <span class="s2">&quot;http&quot;</span><span class="p">:</span> <span class="s2">&quot;10.10.1.10:3128&quot;</span><span class="p">,</span>    <span class="c1"># use http://10.10.1.10:3128 instead</span>
<span class="p">}</span>

<span class="c1"># In requests 1.x, this was legal, in requests 2.x,</span>
<span class="c1">#  this raises requests.exceptions.MissingSchema</span>
<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;http://example.org&quot;</span><span class="p">,</span> <span class="n">proxies</span><span class="o">=</span><span class="n">proxies</span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="behavioural-changes">
<h5>Behavioural Changes<a class="headerlink" href="#behavioural-changes" title="Permalink to this headline">¶</a></h5>
<ul class="simple">
<li>Keys in the <code class="docutils literal"><span class="pre">headers</span></code> dictionary are now native strings on all Python
versions, i.e. bytestrings on Python 2 and unicode on Python 3. If the
keys are not native strings (unicode on Python2 or bytestrings on Python 3)
they will be converted to the native string type assuming UTF-8 encoding.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="section" id="contributor-guide">
<h2>Contributor Guide<a class="headerlink" href="#contributor-guide" title="Permalink to this headline">¶</a></h2>
<p>If you want to contribute to the project, this part of the documentation is for
you.</p>
<div class="toctree-wrapper compound">
<span id="document-dev/contributing"></span><div class="section" id="contributor-s-guide">
<span id="contributing"></span><h3>Contributor&#8217;s Guide<a class="headerlink" href="#contributor-s-guide" title="Permalink to this headline">¶</a></h3>
<p>If you&#8217;re reading this you&#8217;re probably interested in contributing to
Requests. First, We&#8217;d like to say: thank you! Open source projects
live-and-die based on the support they receive from others, and the fact that
you&#8217;re even considering supporting Requests is very generous of
you.</p>
<p>This document lays out guidelines and advice for contributing to Requests.
If you&#8217;re thinking of contributing, start by reading this thoroughly and
getting a feel for how contributing to the project works. If you have any
questions, feel free to reach out to either <a class="reference external" href="#">Ian Cordasco</a> or <a class="reference external" href="#">Cory Benfield</a>,
the primary maintainers.</p>
<p>The guide is split into sections based on the type of contribution you&#8217;re
thinking of making, with a section that covers general guidelines for all
contributors.</p>
<div class="section" id="all-contributions">
<h4>All Contributions<a class="headerlink" href="#all-contributions" title="Permalink to this headline">¶</a></h4>
<div class="section" id="be-cordial">
<h5>Be Cordial<a class="headerlink" href="#be-cordial" title="Permalink to this headline">¶</a></h5>
<p><strong>Be cordial or be on your way.</strong></p>
<p>Requests has one very important rule governing all forms of contribution,
including reporting bugs or requesting features. This golden rule is
<a class="reference external" href="#">be cordial or be on your way</a>. <strong>All contributions are welcome</strong>, as long as
everyone involved is treated with respect.</p>
</div>
<div class="section" id="get-early-feedback">
<span id="early-feedback"></span><h5>Get Early Feedback<a class="headerlink" href="#get-early-feedback" title="Permalink to this headline">¶</a></h5>
<p>If you are contributing, do not feel the need to sit on your contribution until
it is perfectly polished and complete. It helps everyone involved for you to
seek feedback as early as you possibly can. Submitting an early, unfinished
version of your contribution for feedback in no way prejudices your chances of
getting that contribution accepted, and can save you from putting a lot of work
into a contribution that is not suitable for the project.</p>
</div>
<div class="section" id="contribution-suitability">
<h5>Contribution Suitability<a class="headerlink" href="#contribution-suitability" title="Permalink to this headline">¶</a></h5>
<p>The project maintainer has the last word on whether or not a contribution is
suitable for Requests. All contributions will be considered, but from time
to time contributions will be rejected because they do not suit the project.</p>
<p>If your contribution is rejected, don&#8217;t despair! So long as you followed these
guidelines, you&#8217;ll have a much better chance of getting your next contribution
accepted.</p>
</div>
</div>
<div class="section" id="code-contributions">
<h4>Code Contributions<a class="headerlink" href="#code-contributions" title="Permalink to this headline">¶</a></h4>
<div class="section" id="steps">
<h5>Steps<a class="headerlink" href="#steps" title="Permalink to this headline">¶</a></h5>
<p>When contributing code, you&#8217;ll want to follow this checklist:</p>
<ol class="arabic simple">
<li>Fork the repository on GitHub.</li>
<li>Run the tests to confirm they all pass on your system. If they don&#8217;t, you&#8217;ll
need to investigate why they fail. If you&#8217;re unable to diagnose this
yourself, raise it as a bug report by following the guidelines in this
document: <a class="reference internal" href="#bug-reports"><span>Bug Reports</span></a>.</li>
<li>Write tests that demonstrate your bug or feature. Ensure that they fail.</li>
<li>Make your change.</li>
<li>Run the entire test suite again, confirming that all tests pass <em>including
the ones you just added</em>.</li>
<li>Send a GitHub Pull Request to the main repository&#8217;s <code class="docutils literal"><span class="pre">master</span></code> branch.
GitHub Pull Requests are the expected method of code collaboration on this
project.</li>
</ol>
<p>The following sub-sections go into more detail on some of the points above.</p>
</div>
<div class="section" id="code-review">
<h5>Code Review<a class="headerlink" href="#code-review" title="Permalink to this headline">¶</a></h5>
<p>Contributions will not be merged until they&#8217;ve been code reviewed. You should
implement any code review feedback unless you strongly object to it. In the
event that you object to the code review feedback, you should make your case
clearly and calmly. If, after doing so, the feedback is judged to still apply,
you must either apply the feedback or withdraw your contribution.</p>
</div>
<div class="section" id="new-contributors">
<h5>New Contributors<a class="headerlink" href="#new-contributors" title="Permalink to this headline">¶</a></h5>
<p>If you are new or relatively new to Open Source, welcome! Requests aims to
be a gentle introduction to the world of Open Source. If you&#8217;re concerned about
how best to contribute, please consider mailing a maintainer (listed above) and
asking for help.</p>
<p>Please also check the <a class="reference internal" href="#early-feedback"><span>Get Early Feedback</span></a> section.</p>
</div>
</div>
<div class="section" id="documentation-contributions">
<h4>Documentation Contributions<a class="headerlink" href="#documentation-contributions" title="Permalink to this headline">¶</a></h4>
<p>Documentation improvements are always welcome! The documentation files live in
the <code class="docutils literal"><span class="pre">docs/</span></code> directory of the codebase. They&#8217;re written in
<a class="reference external" href="#">reStructuredText</a>, and use <a class="reference external" href="#">Sphinx</a> to generate the full suite of
documentation.</p>
<p>When contributing documentation, please attempt to follow the style of the
documentation files. This means a soft-limit of 79 characters wide in your text
files and a semi-formal prose style.</p>
</div>
<div class="section" id="bug-reports">
<span id="id1"></span><h4>Bug Reports<a class="headerlink" href="#bug-reports" title="Permalink to this headline">¶</a></h4>
<p>Bug reports are hugely important! Before you raise one, though, please check
through the <a class="reference external" href="#">GitHub issues</a>, <strong>both open and closed</strong>, to confirm that the bug
hasn&#8217;t been reported before. Duplicate bug reports are a huge drain on the time
of other contributors, and should be avoided as much as possible.</p>
</div>
<div class="section" id="feature-requests">
<h4>Feature Requests<a class="headerlink" href="#feature-requests" title="Permalink to this headline">¶</a></h4>
<p>Requests is in a perpetual feature freeze. The maintainers believe that
requests contains every major feature currently required by the vast majority
of users.</p>
<p>If you believe there is a feature missing, feel free to raise a feature
request, but please do be aware that the overwhelming likelihood is that your
feature request will not be accepted.</p>
</div>
</div>
<span id="document-dev/philosophy"></span><div class="section" id="development-philosophy">
<h3>Development Philosophy<a class="headerlink" href="#development-philosophy" title="Permalink to this headline">¶</a></h3>
<p>Requests is an open but opinionated library, created by an open but opinionated developer.</p>
<div class="section" id="management-style">
<h4>Management Style<a class="headerlink" href="#management-style" title="Permalink to this headline">¶</a></h4>
<p><a class="reference external" href="#">Kenneth Reitz</a> is the BDFL. He has final say in any decision related to the Requests project. Kenneth is responsible for the direction and form of the library. In addition to making decisions based on technical merit, he is responsible for making decisions based on the development philosophy of Requests. Only Kenneth may merge code into Requests.</p>
<p><a class="reference external" href="#">Ian Cordasco</a> and <a class="reference external" href="#">Cory Benfield</a> are the core contributors. They are responsible for triaging bug reports, reviewing pull requests and ensuring that Kenneth is kept up to speed with developments around the library. The day-to-day managing of the project is done by the core contributors. They are responsible for making judgements about whether or not a feature request is likely to be accepted by Kenneth. They do not have the authority to change code or merge code changes, though they may change documentation. Their word is not final.</p>
</div>
<div class="section" id="values">
<h4>Values<a class="headerlink" href="#values" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Simplicity is always better than functionality.</li>
<li>Listen to everyone, then disregard it.</li>
<li>The API is all that matters. Everything else is secondary.</li>
<li>Fit the 90% use-case. Ignore the nay-sayers.</li>
</ul>
</div>
<div class="section" id="semantic-versioning">
<h4>Semantic Versioning<a class="headerlink" href="#semantic-versioning" title="Permalink to this headline">¶</a></h4>
<p>For many years, the open source community has been plagued with version number dystonia. Numbers vary so greatly from project to project, they are practically meaningless.</p>
<p>Requests uses <a class="reference external" href="#">Semantic Versioning</a>. This specification seeks to put an end to this madness with a small set of practical guidelines for you and your colleagues to use in your next project.</p>
</div>
<div class="section" id="standard-library">
<h4>Standard Library?<a class="headerlink" href="#standard-library" title="Permalink to this headline">¶</a></h4>
<p>Requests has no <em>active</em> plans to be included in the standard library. This decision has been discussed at length with Guido as well as numerous core developers.</p>
<p>Essentially, the standard library is where a library goes to die. It is appropriate for a module to be included when active development is no longer necessary.</p>
<p>Requests just reached v1.0.0. This huge milestone marks a major step in the right direction.</p>
</div>
<div class="section" id="linux-distro-packages">
<h4>Linux Distro Packages<a class="headerlink" href="#linux-distro-packages" title="Permalink to this headline">¶</a></h4>
<p>Distributions have been made for many Linux repositories, including: Ubuntu, Debian, RHEL, and Arch.</p>
<p>These distributions are sometimes divergent forks, or are otherwise not kept up-to-date with the latest code and bugfixes. PyPI (and its mirrors) and GitHub are the official distribution sources; alternatives are not supported by the Requests project.</p>
</div>
</div>
<span id="document-dev/todo"></span><div class="section" id="how-to-help">
<h3>How to Help<a class="headerlink" href="#how-to-help" title="Permalink to this headline">¶</a></h3>
<p>Requests is under active development, and contributions are more than welcome!</p>
<ol class="arabic simple">
<li>Check for open issues or open a fresh issue to start a discussion around a bug.
There is a Contributor Friendly tag for issues that should be ideal for people who are not very
familiar with the codebase yet.</li>
<li>Fork <a class="reference external" href="#">the repository</a> on GitHub and start making your
changes to a new branch.</li>
<li>Write a test which shows that the bug was fixed.</li>
<li>Send a pull request and bug the maintainer until it gets merged and published. :)
Make sure to add yourself to <a class="reference external" href="#">AUTHORS</a>.</li>
</ol>
<div class="section" id="feature-freeze">
<h4>Feature Freeze<a class="headerlink" href="#feature-freeze" title="Permalink to this headline">¶</a></h4>
<p>As of v1.0.0, Requests has now entered a feature freeze. Requests for new
features and Pull Requests implementing those features will not be accepted.</p>
</div>
<div class="section" id="development-dependencies">
<h4>Development Dependencies<a class="headerlink" href="#development-dependencies" title="Permalink to this headline">¶</a></h4>
<p>You&#8217;ll need to install py.test in order to run the Requests&#8217; test suite:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ pip install -r requirements.txt
$ py.test
platform darwin -- Python 2.7.3 -- pytest-2.3.4
collected 25 items

test_requests.py .........................
25 passed in 3.50 seconds
</pre></div>
</div>
</div>
<div class="section" id="runtime-environments">
<h4>Runtime Environments<a class="headerlink" href="#runtime-environments" title="Permalink to this headline">¶</a></h4>
<p>Requests currently supports the following versions of Python:</p>
<ul class="simple">
<li>Python 2.6</li>
<li>Python 2.7</li>
<li>Python 3.1</li>
<li>Python 3.2</li>
<li>Python 3.3</li>
<li>PyPy 1.9</li>
</ul>
<p>Support for Python 3.1 and 3.2 may be dropped at any time.</p>
<p>Google App Engine will never be officially supported. Pull Requests for compatibility will be accepted, as long as they don&#8217;t complicate the codebase.</p>
</div>
<div class="section" id="are-you-crazy">
<h4>Are you crazy?<a class="headerlink" href="#are-you-crazy" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>SPDY support would be awesome. No C extensions.</li>
</ul>
</div>
<div class="section" id="downstream-repackaging">
<h4>Downstream Repackaging<a class="headerlink" href="#downstream-repackaging" title="Permalink to this headline">¶</a></h4>
<p>If you are repackaging Requests, please note that you must also redistribute the <code class="docutils literal"><span class="pre">cacerts.pem</span></code> file in order to get correct SSL functionality.</p>
</div>
</div>
<span id="document-dev/authors"></span><div class="section" id="authors">
<h3>Authors<a class="headerlink" href="#authors" title="Permalink to this headline">¶</a></h3>
<p>Requests is written and maintained by Kenneth Reitz and
various contributors:</p>
<div class="section" id="keepers-of-the-three-crystals">
<h4>Keepers of the Three Crystals<a class="headerlink" href="#keepers-of-the-three-crystals" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Kenneth Reitz &lt;<a class="reference external" href="mailto:me&#37;&#52;&#48;kennethreitz&#46;org">me<span>&#64;</span>kennethreitz<span>&#46;</span>org</a>&gt; <a class="reference external" href="#">&#64;kennethreitz</a>, Keeper of the Master Crystal.</li>
<li>Cory Benfield &lt;<a class="reference external" href="mailto:cory&#37;&#52;&#48;lukasa&#46;co&#46;uk">cory<span>&#64;</span>lukasa<span>&#46;</span>co<span>&#46;</span>uk</a>&gt; <a class="reference external" href="#">&#64;lukasa</a></li>
<li>Ian Cordasco &lt;<a class="reference external" href="mailto:graffatcolmingov&#37;&#52;&#48;gmail&#46;com">graffatcolmingov<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; <a class="reference external" href="#">&#64;sigmavirus24</a></li>
</ul>
</div>
<div class="section" id="urllib3">
<h4>Urllib3<a class="headerlink" href="#urllib3" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Andrey Petrov &lt;<a class="reference external" href="mailto:andrey&#46;petrov&#37;&#52;&#48;shazow&#46;net">andrey<span>&#46;</span>petrov<span>&#64;</span>shazow<span>&#46;</span>net</a>&gt;</li>
</ul>
</div>
<div class="section" id="patches-and-suggestions">
<h4>Patches and Suggestions<a class="headerlink" href="#patches-and-suggestions" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>Various Pocoo Members</li>
<li>Chris Adams</li>
<li>Flavio Percoco Premoli</li>
<li>Dj Gilcrease</li>
<li>Justin Murphy</li>
<li>Rob Madole</li>
<li>Aram Dulyan</li>
<li>Johannes Gorset</li>
<li>村山めがね (Megane Murayama)</li>
<li>James Rowe</li>
<li>Daniel Schauenberg</li>
<li>Zbigniew Siciarz</li>
<li>Daniele Tricoli &#8216;Eriol&#8217;</li>
<li>Richard Boulton</li>
<li>Miguel Olivares &lt;<a class="reference external" href="mailto:miguel&#37;&#52;&#48;moliware&#46;com">miguel<span>&#64;</span>moliware<span>&#46;</span>com</a>&gt;</li>
<li>Alberto Paro</li>
<li>Jérémy Bethmont</li>
<li>潘旭 (Xu Pan)</li>
<li>Tamás Gulácsi</li>
<li>Rubén Abad</li>
<li>Peter Manser</li>
<li>Jeremy Selier</li>
<li>Jens Diemer</li>
<li>Alex (<a class="reference external" href="#">&#64;alopatin</a>)</li>
<li>Tom Hogans &lt;<a class="reference external" href="mailto:tomhsx&#37;&#52;&#48;gmail&#46;com">tomhsx<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Armin Ronacher</li>
<li>Shrikant Sharat Kandula</li>
<li>Mikko Ohtamaa</li>
<li>Den Shabalin</li>
<li>Daniel Miller &lt;<a class="reference external" href="mailto:danielm&#37;&#52;&#48;vs-networks&#46;com">danielm<span>&#64;</span>vs-networks<span>&#46;</span>com</a>&gt;</li>
<li>Alejandro Giacometti</li>
<li>Rick Mak</li>
<li>Johan Bergström</li>
<li>Josselin Jacquard</li>
<li>Travis N. Vaught</li>
<li>Fredrik Möllerstrand</li>
<li>Daniel Hengeveld</li>
<li>Dan Head</li>
<li>Bruno Renié</li>
<li>David Fischer</li>
<li>Joseph McCullough</li>
<li>Juergen Brendel</li>
<li>Juan Riaza</li>
<li>Ryan Kelly</li>
<li>Rolando Espinoza La fuente</li>
<li>Robert Gieseke</li>
<li>Idan Gazit</li>
<li>Ed Summers</li>
<li>Chris Van Horne</li>
<li>Christopher Davis</li>
<li>Ori Livneh</li>
<li>Jason Emerick</li>
<li>Bryan Helmig</li>
<li>Jonas Obrist</li>
<li>Lucian Ursu</li>
<li>Tom Moertel</li>
<li>Frank Kumro Jr</li>
<li>Chase Sterling</li>
<li>Marty Alchin</li>
<li>takluyver</li>
<li>Ben Toews (<a class="reference external" href="#">&#64;mastahyeti</a>)</li>
<li>David Kemp</li>
<li>Brendon Crawford</li>
<li>Denis (<a class="reference external" href="#">&#64;Telofy</a>)</li>
<li>Matt Giuca</li>
<li>Adam Tauber</li>
<li>Honza Javorek</li>
<li>Brendan Maguire &lt;<a class="reference external" href="mailto:maguire&#46;brendan&#37;&#52;&#48;gmail&#46;com">maguire<span>&#46;</span>brendan<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Chris Dary</li>
<li>Danver Braganza &lt;<a class="reference external" href="mailto:danverbraganza&#37;&#52;&#48;gmail&#46;com">danverbraganza<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Max Countryman</li>
<li>Nick Chadwick</li>
<li>Jonathan Drosdeck</li>
<li>Jiri Machalek</li>
<li>Steve Pulec</li>
<li>Michael Kelly</li>
<li>Michael Newman &lt;<a class="reference external" href="mailto:newmaniese&#37;&#52;&#48;gmail&#46;com">newmaniese<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Jonty Wareing &lt;<a class="reference external" href="mailto:jonty&#37;&#52;&#48;jonty&#46;co&#46;uk">jonty<span>&#64;</span>jonty<span>&#46;</span>co<span>&#46;</span>uk</a>&gt;</li>
<li>Shivaram Lingamneni</li>
<li>Miguel Turner</li>
<li>Rohan Jain (<a class="reference external" href="#">&#64;crodjer</a>)</li>
<li>Justin Barber &lt;<a class="reference external" href="mailto:barber&#46;justin&#37;&#52;&#48;gmail&#46;com">barber<span>&#46;</span>justin<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Roman Haritonov (<a class="reference external" href="#">&#64;reclosedev</a>)</li>
<li>Josh Imhoff &lt;<a class="reference external" href="mailto:joshimhoff13&#37;&#52;&#48;gmail&#46;com">joshimhoff13<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Arup Malakar &lt;<a class="reference external" href="mailto:amalakar&#37;&#52;&#48;gmail&#46;com">amalakar<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Danilo Bargen (<a class="reference external" href="#">&#64;dbrgn</a>)</li>
<li>Torsten Landschoff</li>
<li>Michael Holler (<a class="reference external" href="#">&#64;apotheos</a>)</li>
<li>Timnit Gebru</li>
<li>Sarah Gonzalez</li>
<li>Victoria Mo</li>
<li>Leila Muhtasib</li>
<li>Matthias Rahlf &lt;<a class="reference external" href="mailto:matthias&#37;&#52;&#48;webding&#46;de">matthias<span>&#64;</span>webding<span>&#46;</span>de</a>&gt;</li>
<li>Jakub Roztocil &lt;<a class="reference external" href="mailto:jakub&#37;&#52;&#48;roztocil&#46;name">jakub<span>&#64;</span>roztocil<span>&#46;</span>name</a>&gt;</li>
<li>Rhys Elsmore</li>
<li>André Graf (<a class="reference external" href="#">&#64;dergraf</a>)</li>
<li>Stephen Zhuang (<a class="reference external" href="#">&#64;everbird</a>)</li>
<li>Martijn Pieters</li>
<li>Jonatan Heyman</li>
<li>David Bonner &lt;<a class="reference external" href="mailto:dbonner&#37;&#52;&#48;gmail&#46;com">dbonner<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;rascalking</a>)</li>
<li>Vinod Chandru</li>
<li>Johnny Goodnow &lt;<a class="reference external" href="mailto:j&#46;goodnow29&#37;&#52;&#48;gmail&#46;com">j<span>&#46;</span>goodnow29<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Denis Ryzhkov &lt;<a class="reference external" href="mailto:denisr&#37;&#52;&#48;denisr&#46;com">denisr<span>&#64;</span>denisr<span>&#46;</span>com</a>&gt;</li>
<li>Wilfred Hughes &lt;<a class="reference external" href="mailto:me&#37;&#52;&#48;wilfred&#46;me&#46;uk">me<span>&#64;</span>wilfred<span>&#46;</span>me<span>&#46;</span>uk</a>&gt;</li>
<li>Dmitry Medvinsky &lt;<a class="reference external" href="mailto:me&#37;&#52;&#48;dmedvinsky&#46;name">me<span>&#64;</span>dmedvinsky<span>&#46;</span>name</a>&gt;</li>
<li>Bryce Boe &lt;<a class="reference external" href="mailto:bbzbryce&#37;&#52;&#48;gmail&#46;com">bbzbryce<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;bboe</a>)</li>
<li>Colin Dunklau &lt;<a class="reference external" href="mailto:colin&#46;dunklau&#37;&#52;&#48;gmail&#46;com">colin<span>&#46;</span>dunklau<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;cdunklau</a>)</li>
<li>Bob Carroll &lt;<a class="reference external" href="mailto:bob&#46;carroll&#37;&#52;&#48;alum&#46;rit&#46;edu">bob<span>&#46;</span>carroll<span>&#64;</span>alum<span>&#46;</span>rit<span>&#46;</span>edu</a>&gt; (<a class="reference external" href="#">&#64;rcarz</a>)</li>
<li>Hugo Osvaldo Barrera &lt;<a class="reference external" href="mailto:hugo&#37;&#52;&#48;osvaldobarrera&#46;com&#46;ar">hugo<span>&#64;</span>osvaldobarrera<span>&#46;</span>com<span>&#46;</span>ar</a>&gt; (<a class="reference external" href="#">&#64;hobarrera</a>)</li>
<li>Łukasz Langa &lt;<a class="reference external" href="mailto:lukasz&#37;&#52;&#48;langa&#46;pl">lukasz<span>&#64;</span>langa<span>&#46;</span>pl</a>&gt;</li>
<li>Dave Shawley &lt;<a class="reference external" href="mailto:daveshawley&#37;&#52;&#48;gmail&#46;com">daveshawley<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>James Clarke (<a class="reference external" href="#">&#64;jam</a>)</li>
<li>Kevin Burke &lt;<a class="reference external" href="mailto:kev&#37;&#52;&#48;inburke&#46;com">kev<span>&#64;</span>inburke<span>&#46;</span>com</a>&gt;</li>
<li>Flavio Curella</li>
<li>David Pursehouse &lt;<a class="reference external" href="mailto:david&#46;pursehouse&#37;&#52;&#48;gmail&#46;com">david<span>&#46;</span>pursehouse<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;dpursehouse</a>)</li>
<li>Jon Parise (<a class="reference external" href="#">&#64;jparise</a>)</li>
<li>Alexander Karpinsky (<a class="reference external" href="#">&#64;homm86</a>)</li>
<li>Marc Schlaich (<a class="reference external" href="#">&#64;schlamar</a>)</li>
<li>Park Ilsu &lt;<a class="reference external" href="mailto:daftonshady&#37;&#52;&#48;gmail&#46;com">daftonshady<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;daftshady</a>)</li>
<li>Matt Spitz (<a class="reference external" href="#">&#64;mattspitz</a>)</li>
<li>Vikram Oberoi (<a class="reference external" href="#">&#64;voberoi</a>)</li>
<li>Can Ibanoglu &lt;<a class="reference external" href="mailto:can&#46;ibanoglu&#37;&#52;&#48;gmail&#46;com">can<span>&#46;</span>ibanoglu<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;canibanoglu</a>)</li>
<li>Thomas Weißschuh &lt;<a class="reference external" href="mailto:thomas&#37;&#52;&#48;t-8ch&#46;de">thomas<span>&#64;</span>t-8ch<span>&#46;</span>de</a>&gt; (<a class="reference external" href="#">&#64;t-8ch</a>)</li>
<li>Jayson Vantuyl &lt;<a class="reference external" href="mailto:jayson&#37;&#52;&#48;aggressive&#46;ly">jayson<span>&#64;</span>aggressive<span>&#46;</span>ly</a>&gt;</li>
<li>Pengfei.X &lt;<a class="reference external" href="mailto:pengphy&#37;&#52;&#48;gmail&#46;com">pengphy<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Kamil Madac &lt;<a class="reference external" href="mailto:kamil&#46;madac&#37;&#52;&#48;gmail&#46;com">kamil<span>&#46;</span>madac<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;</li>
<li>Michael Becker &lt;<a class="reference external" href="mailto:mike&#37;&#52;&#48;beckerfuffle&#46;com">mike<span>&#64;</span>beckerfuffle<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;beckerfuffle</a>)</li>
<li>Erik Wickstrom &lt;<a class="reference external" href="mailto:erik&#37;&#52;&#48;erikwickstrom&#46;com">erik<span>&#64;</span>erikwickstrom<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;erikwickstrom</a>)</li>
<li>Константин Подшумок (<a class="reference external" href="#">&#64;podshumok</a>)</li>
<li>Ben Bass (<a class="reference external" href="#">&#64;codedstructure</a>)</li>
<li>Jonathan Wong &lt;<a class="reference external" href="mailto:evolutionace&#37;&#52;&#48;gmail&#46;com">evolutionace<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;ContinuousFunction</a>)</li>
<li>Martin Jul (<a class="reference external" href="#">&#64;mjul</a>)</li>
<li>Joe Alcorn (<a class="reference external" href="#">&#64;buttscicles</a>)</li>
<li>Syed Suhail Ahmed &lt;<a class="reference external" href="mailto:ssuhail&#46;ahmed93&#37;&#52;&#48;gmail&#46;com">ssuhail<span>&#46;</span>ahmed93<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;syedsuhail</a>)</li>
<li>Scott Sadler (<a class="reference external" href="#">&#64;ssadler</a>)</li>
<li>Arthur Darcet (<a class="reference external" href="#">&#64;arthurdarcet</a>)</li>
<li>Ulrich Petri (<a class="reference external" href="#">&#64;ulope</a>)</li>
<li>Muhammad Yasoob Ullah Khalid &lt;<a class="reference external" href="mailto:yasoob&#46;khld&#37;&#52;&#48;gmail&#46;com">yasoob<span>&#46;</span>khld<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt; (<a class="reference external" href="#">&#64;yasoob</a>)</li>
<li>Paul van der Linden (<a class="reference external" href="#">&#64;pvanderlinden</a>)</li>
<li>Colin Dickson (<a class="reference external" href="#">&#64;colindickson</a>)</li>
<li>Smiley Barry (<a class="reference external" href="#">&#64;smiley</a>)</li>
<li>Shagun Sodhani (<a class="reference external" href="#">&#64;shagunsodhani</a>)</li>
<li>Robin Linderborg (<a class="reference external" href="#">&#64;vienno</a>)</li>
<li>Brian Samek(<a href="#id1"><span class="problematic" id="id2">`&#64;bsamek &lt;https://github.com/bsamek`_</span></a>)</li>
</ul>
</div>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper"><p class="logo">
  <a href="index.html#document-index">
    <img class="logo" src="_static/requests-sidebar.png" title="Rezzy the Requests Sea Turtle"/>
  </a>
</p>

<p>
  <iframe src="#"
    allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>

<p>
  Requests is an elegant and simple HTTP library for Python, built for
  human beings.
</p>


<p>
  <a href="#" class="gumroad-button">Buy Requests Pro</a>
</p>


<h3>Get Updates</h3>
<p>Receive updates on new releases and upcoming projects.</p>

<p><a href="#">Subscribe to Newsletter</a></p>


<h3>Translations</h3>
<ul>
<li><a href="#">English</a></li>
<li><a href="#">French</a></li>
<li><a href="#">German</a></li>
<li><a href="#">Japanese</a></li>
<li><a href="#">Chinese</a></li>
<li><a href="#">Portuguese</a></li>
<li><a href="#">Italian</a></li>
<li><a href="#">Spanish</a></li>
</ul>

<h3>Useful Links</h3>
<ul>
  <li><a href="#">Recommended Packages and Extensions</a></li>

  <p></p>

  <li><a href="#">Requests @ GitHub</a></li>
  <li><a href="#">Requests @ PyPI</a></li>
  <li><a href="#">Issue Tracker</a></li>
  <li><a href="#">Release History</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy; Copyright 2015. A <a href="#">Kenneth Reitz</a> Project.
    </div>


    <script type="text/javascript">
    /* <![CDATA[ */
        (function() {
            var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
            s.type = 'text/javascript';
            s.async = true;
            s.src = "#";
            t.parentNode.insertBefore(s, t);
        })();
    /* ]]> */
    </script>
        <script type="text/javascript">
    setTimeout(function(){var a=document.createElement("script");
    var b=document.getElementsByTagName("script")[0];
    a.src=document.location.protocol+"//dnn506yrbagrg.cloudfront.net/pages/scripts/0013/7219.js?"+Math.floor(new Date().getTime()/3600000);
    a.async=true;a.type="text/javascript";b.parentNode.insertBefore(a,b)}, 1);
    </script>

    <script type="text/javascript">
        new HelloBar(36402,48802);
    </script>


    <script type="text/javascript">

      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-8742933-11']);
      _gaq.push(['_setDomainName', 'none']);
      _gaq.push(['_setAllowLinker', true]);
      _gaq.push(['_trackPageview']);

      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ("#" == document.location.protocol ? "#" : "#") + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();

    </script>

    <script type="text/javascript">
  (function() {
    window._pa = window._pa || {};
    _pa.productId = "requests-docs";
    var pa = document.createElement('script'); pa.type = 'text/javascript'; pa.async = true;
    pa.src = ("#" == document.location.protocol ? "#" : "#") + "//tag.perfectaudience.com/serve/5226171f87bc6890da0000a0.js";
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(pa, s);
  })();
</script>
  </body>
</html>